Manage Personal Access Tokens in Agility

A Personal Access Token (PAT) lets the Agility CLI, your own scripts and a CI pipeline call the Management API as you, without a browser sign-in. You can create, rename, disable, enable and delete your tokens in Agility, from your profile menu. For what a token can and can't do, see Personal Access Tokens.

Before you start

• Use the account the token should act as. A token has the same permissions as the user who creates it, on every instance that user can reach. For a shared pipeline, sign in as a dedicated automation user rather than a person.
• You need the Develop or Manage permission on the instance you have open. Without it, Personal Access Tokens doesn't appear in your profile menu. Open an instance where you have it. The tokens themselves aren't tied to that instance.

Open your tokens

1. Select your avatar in the top-right corner of Agility.
2. Select Personal Access Tokens.

The list shows every token you've created, whichever instance you open it from. Each token shows when it was created, when it expires and when it was last used, and its status: Enabled, Disabled or Expired. A token that expires within seven days says so.

Create a token

1. Select Create Token.
2. In Name, say where the token will be used, for example CI pipeline or Nightly content sync. Names are up to 100 characters, and each of your tokens needs a different name.
3. In Expiration, choose how long the token lasts: 30 days, 90 days (the default), 6 months, 1 year or 2 years.
4. Select Create Token.
5. Select Copy Token, and store the token somewhere safe, such as your CI system's secrets or a password manager.
6. Select Done.

Use the token

With the Agility CLI, pass the token as --token or set AGILITY_TOKEN:

AGILITY_TOKEN="<your token>" agility pull --sourceGuid="<instance guid>" --headless

Your own scripts and the Management SDK send it in the Authorization header, as Bearer <your token>. For pipelines, see the CLI CI/CD Integration Guide.

Rename a token

1. Hover over the token and select Rename (the pencil icon).
2. Enter the new name and select Save.

Renaming doesn't change the token's value or its expiry date, so anything using it keeps working.

Disable or enable a token

Hover over the token and select Disable (the pause icon). Anything using the token stops working until you enable it again with Enable (the play icon).

Disabling is useful when you think a token may have leaked, or to check that nothing still uses it before you delete it. A disabled token doesn't count towards your limit of 10 active tokens.

An expired token can't be enabled again. Create a new one.

Delete a token

1. Hover over the token and select Delete (the trash icon).
2. Select Delete to confirm.

Anything using the token stops working straight away, and you can't undo it.

Limits

Limit	Value
Active tokens per user	10. Disabled and expired tokens don't count
Longest expiry	2 years
Tokens created	5 an hour

When you have 10 active tokens, Create Token is unavailable. Disable or delete a token you don't need first.

Troubleshooting

What you see	What to do
Personal Access Tokens isn't in your profile menu	You need the Develop or Manage permission on the instance you have open. Open another instance, or ask an admin
Create Token is greyed out	You have 10 active tokens. Disable or delete one
An error about too many requests when you create a token	You've created 5 tokens in the last hour. Wait, then try again
A script gets 401 with a token that used to work	The token has expired, been disabled or deleted, or the user who created it has been suspended or removed. Check its status in the list

Related

• Personal Access Tokens: what tokens are and the rules that apply to them
• Create a Personal Access Token with the API: create and manage tokens from a terminal
• CLI CI/CD Integration Guide