To carry out operations on the products you own at Gandi, you can either use the user interface and follow the various menu prompts, or you can choose to use the API (application programming interface) to automate these tasks or to perform bulk operations, such as renewing a large number of domains. In either case, you need to log on to carry out these actions, and the API has until now required the user to possess an API key, a unique and personal string of characters generated on the user’s account. This protocol has a number of shortcomings, however, and has been deprecated in favor of a new Personal Access Token (PAT) system.
Deprecated keys
Previously, use of Gandi’s API had required identification by means of a key. This key could be obtained by the user via his or her account (Organizations section) and could be used for an unlimited period of time and for all possible operations at Gandi. The clear advantage of this login method was its simplicity. The key, once entered into the program responsible for communicating with the API, functioned like a password that was automatically stored by the browser, so that the user never had to worry about it again. But this ease of use also comes at a cost: it didn’t allow for the precise management of authorizations, and could therefore pose security risks.
- Access control limitations: each key was linked to a user, even within an organization, and only that user had the ability to revoke the key. If a company needed to use these keys, it would have to issue new keys each time there was a staff turnover, and make sure that the old ones had been revoked. Furthermore, the key granted access to all services accessible by the user, and could not be limited to certain permissions or products.
- Security limitations: since the API key allowed its user full access to the various services offered by Gandi, if the key were to somehow become compromised, it would be comparable to sharing the account’s login and password, and a third party would be able to modify or delete domains, hostings, SSL certificates, etc.
Fine-tuned management with PAT
To address these potential access management issues, another authentication method is now available. The new system is based on Personal Access Tokens (PATs) with the following features:
- tokens are linked to a single organization, rather than to a specific user who can use the tokens for multiple organizations.-
- they have an expiry date and therefore no longer requires the user revoke it.-
- they are generated by the user and not by Gandi. Each token can be named according to its purpose, and the permissions linked to each token can be limited so that, like the API key, they do not grant access to all the operations allowed by Gandi’s API.-
- it’s now possible for the organization to revoke a token without waiting for the user to do so.
As a result, tokens provide greater control over user access and the functions they are authorized to perform. PATs are “scoped”, i.e. they have a defined scope that limits them to an organization, or a set of pre-defined products, and restricts the type of operations that can be carried for these products.
Thus, it is possible to perform a security audit based on the list of permissions given to the organization’s administrators, and to determine the intended purpose(s) of each of the tokens. Creating these PATs is quick and easy, and managing authorizations is greatly simplified by the scheduled expiration (or revocation by the organization) of the tokens created.
The PAT, in practice
You can now configure your access to Gandi’s API as an organization, rather than as a user:
In your account, go to “Organizations” and select the relevant organization.
1. From your account, go to the “Organizations” section, then select the desired organization.
2. On the “Sharing” page, you can create a new token by clicking on “Create a token”.(Alternatively, you can access this option from the “General View” tab).
3. Give the token a unique name, to identify its use, and set its expiry date (from 7 days to one year).
4. Choose the permissions associated with this token, allowing the user to act on billing, domains, hosting, cloud resources or SSL certificates.
Personal Access Tokens (PATs) are therefore much more than a more flexible substitute for traditional API keys. This mode of identification can still be used for mass actions or repetitive tasks, but it can also be used, for example, to enable a service provider to carry out certain operations without having access to the organization’s entire account. More control, more security: there are many good reasons to switch to PAT.
Tagged in API
