API Access Tokens provide a secure method of accessing the APM API from a script or from an application. In addition, they provide greater control over API access management compared with Basic authentication (i.e., username and password).
Security is improved because username and password do not need to be encoded into scripts or applications that access the API. Also, the authentication token does not carry any user information.
Access management is improved because you can generate access keys granting API access within various scope and permission levels without requiring the creation of additional APM users. A user can generate a token and define the scope of access available to that token to a degree that is equal to or less than that user’s own scope of access.
Another benefit is that single sign-on users do not require a local account to utilize the API.
API Access Tokens are easily generated within APM and are revocable.
There are a few limitations to be aware of:
- Token generation is available to all users except those with custom roles.
- Token permissions are less than or equal to those of the user that created it.
- A token cannot be modified once it is created. You must revoke it then create a new one.
- If the user that created a token is deleted from APM, any tokens they created are immediately revoked.
- Tokens cannot be used to call the observer API endpoint for creating, viewing, or deleting an observer URL. To access the observer API endpoint, use basic authentication or use the interactive API interface.
Create a token
To create an access token:
- Navigate to > Manage Access Tokens.
- Click Add Access Token.
- Enter a token name. This can be a descriptive name that includes spaces.
- Specify an expiration date (or Never).
- The token is revoked automatically at expiration.
- In the Dynamic Access section, check Add all organizations and any in the future if you want the token to access any organizations the user has access to now and in the future (as new organizations are added or removed).
- In the Select Organizations section, check any organizations you want the token to have access to.
- If selected, the selection of organizations is static. New organizations available to the user will not be accessible by the token.
- In the Role section, specify the permissions for the token (less than or equal to the user’s permissions).
- Click Create Token.
- Copy the token and save it. Important: It will not appear again.
- Click Finished.
A user can view the tokens they created. An Organization Admin can view tokens they created as well as token associated with organizations they control.
To view tokens, navigate to > Manage Access Tokens.
Revoke a token
When a token is no longer needed for API authentication it can be revoked. Once revoked, it can no longer be used to access the API.
Users can revoke the tokens they created. Organization Admins can revoke tokens they created as well as those associated with organizations they control.
Tokens can be revoked in three ways: by expiring, when the user that created them is deleted, and manually.
To manually revoke an access token:
- Navigate to > Manage Access Tokens.
- For the token you want to revoke, click Revoke.
- Click Yes, I’m sure.
- The token appears as REVOKED.
Use a token
API access tokens can be used in scripts or in applications accessing the APM API. The token must be passed as an HTTP Request header value under the Authorization heading as a Token. For example, within a curl command:
curl -X GET -H "Authorization: Token <token>" -H "Accept: application/json" "https://<your_APM_node>.pm.appneta.com/api/v3/path"
Token expiry notifications
You will receive an email notification two weeks before a token expires. Prior to expiration you’ll need to create a new token and replace it in all locations it is used.