Manage API accesses with a Personal Access Token¶
Personal Access tokens (PAT) are access code to Gandi Public API, with more “granularity” on the rights than the now deprecated API Key. These tokens allow you to provide access (via the public API) to a single organization, or even restricted to only some of the products of an organization.
Important
Rights provided by a PAT have effects ONLY on the Public API queries. They are not taken in account using the “classic” sharing (or team) of the Gandi administration.
Personal Access Tokens¶
In the contrary of the API keys, which gave a single API access to all the products of all the organizations related to the username, for an undetermined duration, and that can be provided to several persons, a PAT has :
a limited duration,
limited (or full) permissions on all or part of the products (called resources) of an organization,
several “instances” of a token with the same duration and permissions, but named differently, so you know who uses which token.
Personal Access Tokens (PATs) allow you to improve the security of your products, and to manage in detail the access to your products using Gandi Public API.
Create a token¶
Note
You can create a token from several places in your Gandi account : From the Sharing tab in your organizations, from the settings of your Username Settings, and from the now deprecated Developer access
To create a token, follow the instructions above to access to the Sharing page of the concerned organization, go to the bottom of the page and click on Create a token button in the dedicated block.
Name of your PAT¶
You can choose the name you want, so you can find easily if you have several tokens. You can use the name of the person who will use it by example. Just avoid too long names and accented or special characters.
Expires in¶
This mandatory setting defines the validity duration of the token. At the end of the duration, the token will expire automatically and will not be usable again. Available duration are actually of 7 days, 30 days, 60 days, 90 days or 1 year.
Token resources¶
The resources define the entities to whom the user of the token will be allowed to access.
The whole organization means that the token allows the rights (defined below) to all the products of the chosen organization : Domain names and related services (mails, forwarding, …), SSL certificates and the various hosting services.
Restrict to selected products : With this option, the rights of the token will only apply to the chosen products. Just select the products from the dropdown menu and they will be added to the list. You can remove a product by clicking on “x” to its right.
Permissions granted to the token¶
These are the permissions available for each “family” of products, that you can activate or deactivate, for the token to allow. Remember, these rights are for API use only.
When you have completed the various “fields” of the form, click on the Create button to generate the token. Of course, you can use Cancel to return to the sharing page.
Generated Token¶
When you have finished defining the token and created it, you will be redirected to another page displaying it. You will have to use the Copy button to activate the Done button and quit this page. This way, we are sure that you copied the token that you will have to provide to the user needing it.
Remember to keep this token preciously, as it will not be displayed anymore. There is no means to retrieve it.
You will see a “curl” command too. You can copy it, and paste it in a terminal to check the correct operation of the token. If all is correct, you will see the token name and the permissions allowed.
If you see a 401 unauthorized
displayed, something gone wrong. Verify you correctly copy / pasted the command and if there is no error, just delete the token and create a new one.
If you encounter issues, or need additional information, do not hesitate to contact our support team.
Use a token¶
To use a token, you should add an header called Authorization with the value of your token, preceded by “Bearer”. More information here.
-H 'authorization: Bearer a5f72d8e2b391ca6d7104e8b35f9a01c3d4762f9' \
Replace ‘a5f72d8e2b391ca6d7104e8b35f9a01c3d4762f9’ by your own PAT
Revoke a token¶
You can revoke a token when you want :
From Organization :
Log in your Gandi account, and click on ORGANIZATIONS in the left menu.
Click on the concerned organization name (or click on the Manage button, right of the organization).
Click on the “Sharing tab (scroll menu if necessary) on the top of the page.
Search for the concerned token, and click on the trashcan (🗑) icon to its right. Token will be immediately revoked.
From the User account
Log in your Gandi account.
Click on your username on the top right ({username} ⋁ ) and choose Settings.
Search for the Personal Access tokens (PAT) block on the page.
Click on View my personal access tokens.
Search for the concerned token, and click on the trashcan (🗑) icon to its right. The token will be immediately revoked.