Personal API keys

A personal API key is a secret-based API key that belongs to you, not to the organization. It gives spacectl, Terraform and your scripts the same access you have in Spacelift, and nothing more. You create and delete your own keys from your personal settings. Administrators do not create keys for you and do not manage their permissions.

Info

Personal API keys are available on accounts that use the Identity Access Management strategy. An administrator turns them on under Organization settings → API keys → Settings. Accounts that use login policies cannot create personal API keys.

How personal API keys work

A personal API key has no roles of its own. Every time the key is exchanged for a token, Spacelift looks up the person who owns it and gives the token the roles that person holds at that moment:

• Roles assigned to you directly.
• Roles assigned to the IdP groups you were a member of at your last login.

Account ownership and administrator status in your identity provider do not carry over to the key. The key can do what your role bindings allow, so it can never do more than you can.

Because the access comes from you, a personal API key cannot be scoped below your own access. If a script needs less access than you have, use an organization API key with its own roles instead.

A personal API key cannot create API keys or change role bindings, even when you can. Use the web UI or a human session for those tasks.

Create a personal API key

You need at least one role in the account, assigned to you directly or through an IdP group. Spacelift refuses to create a key for a user without a role, because the key would have no access.

A personal API key has the same access as you and stops working when your user is deprovisioned. Do not use it for CI or shared automation. Use an organization API key for anything your team depends on.

1. Click your name in the bottom left corner and select Personal settings.
2. Click Personal API keys, then Create API key.
3. Fill in the details:
   • Name: A name that tells you where the key is used, for example laptop-spacectl or ci-nightly-report.
   • Description: Optional.
   • Expires at: Required. The date is set to three months ahead and can be at most 180 days ahead. After this date the key stops working.
4. Click Create.

Warning

The secret is in a credentials file that your browser downloads once, right after the key is created. Spacelift stores only a hash of it. If you lose the file, reset the key or delete it and create a new one.

You can have at most 100 personal API keys. Revoked and expired keys count toward the limit until you delete them.

If personal API keys are not turned on for your account, the Personal API keys page lets you ask an administrator to turn them on. Administrators get one notification per requesting user. Repeated requests from the same user do not create new notifications.

Create a personal API key with the GraphQL API

You can also create a personal API key from a script that is authenticated as you, for example with a token from spacectl profile export-token. A token obtained from an API key cannot create personal keys.

mutation CreatePersonalKey($input: PersonalApiKeyInput!) {
  personalApiKeyCreate(input: $input) {
    id
    name
    secret
  }
}

{
  "input": {
    "name": "laptop-spacectl",
    "description": "spacectl on my work laptop",
    "expiresAt": 1798761600
  }
}

expiresAt is a Unix timestamp in seconds. It is required and can be at most 180 days ahead. The secret field is returned by this mutation only.

Use a personal API key

A personal API key is used exactly like an organization API key. Exchange the key ID and secret for a token:

mutation GetSpaceliftToken($id: ID!, $secret: String!) {
  apiKeyUser(id: $id, secret: $secret) {
    jwt
  }
}

The token is valid for up to 10 hours and carries your access at the time of the exchange.

The same key ID and secret work with:

• spacectl, through the SPACELIFT_API_KEY_ID and SPACELIFT_API_KEY_SECRET environment variables.
• The Terraform module registry and provider registry, through the credentials in your Terraform configuration file.
• Any GraphQL API client.

Note

A personal API key cannot be used to sign in to the Spacelift web UI. The /apikeytoken sign-in page accepts organization API keys only.

Actions taken with a personal API key appear in the audit trail with the key as the actor and your username next to it.

When your access changes

Your personal API keys follow your access:

• When a role is assigned to you or removed from you, your keys gain or lose it.
• When you join or leave an IdP group, your keys follow at your next login, because Spacelift reads your group membership from the identity provider when you log in.
• When your user is deactivated or removed from the account, your keys are disabled and stay disabled.

A token that was issued before the change can keep the previous access until it expires, which is at most 10 hours after it was issued.

Key states

A personal API key is in one of these states:

State	How a key gets there	What you can do
Active	Created and not past its expiry date.	Edit the name and description, reset the secret, delete.
Expired	Past its expiry date.	Delete.
Revoked	An administrator revoked it, your user was deprovisioned, personal API keys were turned off with existing keys deactivated, or the account moved to login policies.	Delete.

A revoked or expired key can never be enabled again. The Personal API keys page shows the reason and the date next to each revoked key.

Reset the secret

Reset gives an active key a new secret and keeps its ID, name, roles and expiry date. The old secret stops working at once, for tokens in use as well. Reset is not available on a revoked or expired key, or while personal API keys are turned off for the account.

Delete a personal API key

1. Click your name in the bottom left corner and select Personal settings.
2. Click Personal API keys.
3. Click the three dots in the key's row and select Delete.

Deletion takes effect at once, for tokens in use as well. Delete a key when the machine or tool that used it is retired, or when you suspect the secret has leaked.

Personal API keys for administrators

Root administrators see every active personal API key on the account with its owner under Organization settings → API keys → Personal. One person's keys are listed under Organization settings → Users, on the Personal API keys tab of the user.

As an administrator you can revoke a personal API key. Revoke is final: the key stops working at once and nobody can enable it again. The owner still sees the key, with the reason, and can delete it. You cannot assign roles to a personal key, change who owns it, or use it. Its access always comes from its owner.

To take access away from a person and all their keys at once, remove the person's roles or revoke their access.

Turn personal API keys on or off

Under Organization settings → API keys → Settings, the Personal API keys switch controls whether people can create keys. When you turn it off, you choose what happens to the keys that exist:

• Keep existing keys: they keep working, and owners can still delete them. Nobody can create or reset a key.
• Deactivate existing keys: every key stops working at once and is revoked.

Switching the account to login policies revokes every active personal API key. The confirmation names the number of keys. This cannot be undone.

Billing

On paid tiers a person and all their personal API keys count as one seat in the rolling 30 day window, whether the person logs in or only their keys are used. On the Free tier each personal API key that was used in the last 30 days counts against the API key limit, like an organization key.

Related topics

• GraphQL API and organization API keys
• spacectl
• Assigning roles to users
• Identity Access Management