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.

Sharing

If you go to an organization management page, you will see a new “tab” called “Sharing”. This page displays all the sharing actually active in the organization via Teams or the sharing activated on domains or products only.

To access this tab, please follow the instructions below :

  1. Log in your Gandi account, and click on ORGANIZATIONS in the left menu.

  2. Click on the concerned organization name (or click on the Manage button, right of the organization).

  3. Click on the “Sharing tab (scroll menu if necessary) on the top of the page.

Details for all the active permissions related will be displayed. The ones provided by a Personal Access Token are “flagged” with an API icon, next to the username who created the token.

All tokens can be deleted from this page, just use the Trashcan icon on the line of the concerned token. A deleted token removes immediately the rights related to it.

Details of the page

The first table displayed shows the permissions given on the entire organization and its products, rights provided by Teams or PAT. The user column displays the user who generated the right, as defined in the Permissions column. The Teams columns display the Teams allowed by this sharing.

PAT do not display teams (as they are not related to a team) and are flagged with an API icon.

If you have enough rights, you can manage Teams directly from this page via the “Manage teams” button. If you haven’t enough rights, you will just be able to see the team and its members.

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 :

  1. Log in your Gandi account, and click on ORGANIZATIONS in the left menu.

  2. Click on the concerned organization name (or click on the Manage button, right of the organization).

  3. Click on the “Sharing tab (scroll menu if necessary) on the top of the page.

  4. Search for the concerned token, and click on the trashcan (🗑) icon to its right. Token will be immediately revoked.

From the User account

  1. Log in your Gandi account.

  2. Click on your username on the top right ({username} ⋁ ) and choose Settings.

  3. Search for the Personal Access tokens (PAT) block on the page.

  4. Click on View my personal access tokens.

  5. Search for the concerned token, and click on the trashcan (🗑) icon to its right. The token will be immediately revoked.