Service accounts and API tokens
Create service accounts for automation, grant them roles, and manage their keys; create, rotate, and revoke API tokens that act as your own user.
Service accounts and API tokens let scripts and tools call the REST API without signing in to the console.
- An API token acts as the member who created it. It can do what that member's roles allow, limited to the permission scopes you select for the token. Its secret starts with
pc_live_. - A service account is a machine identity of your organization. It gets its own roles, and its keys act as the service account. Its key secrets start with
sak_live_. Because it doesn't depend on a person, a service account keeps working when members leave or change roles.
Neither works with OpenStack tools, such as the openstack CLI or Terraform. For those, create an application credential. To send a token or a key with your requests, see Authenticate with API tokens.
Before you begin
- To create and manage service accounts, their keys, and their role bindings, you need the Owner role, or a custom role with Manage access to Identity & Access.
- To create, rotate, and revoke API tokens, you need the Owner role, or a custom role with Manage access to API Tokens.
- To view service accounts, any role with Read access to Identity & Access is enough. To view API tokens, any role with Read access to API Tokens is enough.
Create a service account
In the console, go to Identity & AccessService Accounts, and select Create service account.
Under Identity, enter an Account name and, optionally, a Description.
Under Role bindings, select the roles to grant. They're granted on the current project.
Under Key, keep Create a key and download the credential turned on to create the first key now, or turn it off.
Select Create + download key, or Create service account if you turned the key off.
If you created a key, select Download JSON and store the file safely. Then select I saved it — go to service accounts.
| Field | Rules |
|---|---|
| Account name | A single letter, or 3–30 characters: lowercase letters, digits, and hyphens, starting with a letter and ending with a letter or a digit. The name must be unique, and you can't change it later. |
| Description | Optional. |
| Roles | Optional. Without a role, the service account exists but can't access anything. You can grant only roles that you're allowed to grant. |
Manage keys
A key is a JSON credential file. Its secret field, which starts with sak_live_, is what you send as Authorization: Bearer <secret>. The file also contains a private key; the platform doesn't use it to authenticate requests.
Create a key. Open the service account, and select Create key. The key is created at once. In the dialog, select Download JSON, store the file, and select I saved it — close.
Important
The key credential is shown once, and you can't download it again. If you lose it, create a new key and revoke the old one.
Revoke a key. On the Keys tab, select Revoke on the key's row, and confirm. Requests with the key are refused at once. You can't undo this.
| Key rule | Value |
|---|---|
| Keys per service account | Up to 5 that aren't revoked. Revoked keys stay listed and don't count. |
| Lifetime | 365 days from creation. Then the key stops working. |
| Status | Active, Expiring soon in the last 30 days, Expired, or Revoked. |
To replace a key without an outage, create a new key, roll it out to your clients, and then revoke the old one. The console flags keys that are older than 90 days.
To create a key, or to enable a disabled service account, you need every permission that the service account's role bindings give.
Grant and remove role bindings
Open the service account, and go to the Role bindings tab.
Select Add binding.
Select a Role and a Scope: the current project, or the subscription. The subscription is offered only when you can grant roles on it.
Select Grant.
A binding on the subscription applies to every project in it. To remove a binding, select Remove on its row, and confirm with Remove binding. The service account loses that access at once. You can also grant a role to a service account from the role's page. See Use built-in and custom roles.
Disable, enable, or delete a service account
| Action | What happens |
|---|---|
| Disable | Requests with the service account's keys are refused at once. Its OpenStack application credentials are deleted. |
| Enable | Its keys work again, unless they've expired or been revoked. Deleted OpenStack application credentials don't come back. |
| Delete | You confirm by typing the account's name. The service account, its keys, and its role bindings are removed, and its OpenStack application credentials are deleted. You can't undo this. |
Create an API token
Go to Identity & AccessAPI tokens, and select Create token.
Enter a Token name.
Under Scopes, select Read or Write for each service the token needs: Compute, Storage, Network, or Billing. Billing has a read scope only.
In Expires, select 30 days, 60 days, 90 days, No expiration, or Custom date. The default is 90 days.
Optional: under IP allowlist, enter the addresses that are allowed to use the token.
Select Create token.
Select Copy token, and store the token in your secrets manager. Confirm that you've stored it, and select Done.
| Field | Rules |
|---|---|
| Token name | 2–63 characters: lowercase letters, numbers, and hyphens, starting with a letter or a number. |
| Scopes | At least one. |
| Custom expiry date | From tomorrow onward. The token expires at 00:00 UTC on that date. |
| Allowed source IPs / CIDRs | IP addresses or CIDR ranges, one per line or separated by commas. Leave it empty to allow any address. Requests from other addresses are refused. |
The secret is shown once. The token's page shows its first 12 characters under Prefix, so that you can recognize the token.
A token works in every project of your organization where you have a role, not only in the project where you created it. Identity & AccessAPI tokens lists the tokens created in the current project. For what each scope allows, see Token scopes.
Rotate an API token
Rotate a token to replace its secret without an outage. Only the member who created a token can rotate it.
In Identity & AccessAPI tokens, open the menu on the token's row, and select Rotate.
On the token's page, select Rotate.
Copy the new secret. It's shown only once.
The previous secret keeps working for 24 hours, so you can update your clients in that time. If the secret has leaked, revoke the token instead of rotating it.
Revoke an API token
In Identity & AccessAPI tokens, open the menu on the token's row, and select Revoke.
Confirm. Requests with the token get 401 Unauthorized from then on.
You can't undo a revocation. Anyone with the Owner role, or a custom role with Manage access to API Tokens, can revoke the tokens listed in the project, including tokens that other members created.
A member's tokens also stop working while the member is deactivated, and they're revoked when the member is removed from your organization. See Deactivate, reactivate, or remove a member.