> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/identity-access-and-administration/personal-api-keys-scopes-expiration-and-revocation.md).

# Personal API Keys: Scopes, Expiration, and Revocation

Personal API keys let applications call supported APIs with a defined scope. Create separate keys for distinct applications so you can rotate or revoke them independently.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FOAKx32i63Bg5qnNGscUX%2FG097.mp4?alt=media&token=02db849c-f97a-41a9-8c82-fb80fa39d4ae>" %}

## Before you begin

An account allowed to create API keys and the permissions required by the application.

## Key concepts

| Term                | Definition                                                                                                                                          |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key             | A secret credential accepted by a supported API or connector. Send it only through the documented authentication field or header.                   |
| Credential rotation | Replacement of an existing secret or authorization with a new one. Check dependent operations before retiring the old credential.                   |
| Revocation          | Withdrawal of a credential or access grant. Check dependent applications and separately issued links when access changes.                           |
| Authorization       | The decision whether a caller can perform an operation on a resource. Check roles, scopes, organization context, and sharing when access is denied. |

## Configuration options

| Option     | Purpose                                          | Behavior                                                                                                  |
| ---------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| Scope      | Restricts which operations the key can perform.  | A scope does not grant resource access its owner lacks.                                                   |
| Expiration | Sets when the key stops authenticating requests. | Replace it before the chosen expiration; an expired key cannot be refreshed as a user session token.      |
| Revocation | Disables a key that must no longer be used.      | Dependent applications must switch to a replacement key; revocation does not update their stored secrets. |

### Choose scopes for the work your application does

| Task                                 | Minimum relevant scopes   |
| ------------------------------------ | ------------------------- |
| Read a project's input schema        | `projects.read`           |
| Start, resume, or cancel a run       | `projects.run`            |
| Read or list runs                    | `analytics.read`          |
| Discover providers and connections   | `connections.read`        |
| Invoke a connected action            | `connections.use`         |
| Create and populate a knowledge base | `kbs.create`, `kbs.index` |
| Read and search a knowledge base     | `kbs.read`, `kbs.query`   |

A complete task can require several rows. For example, start-and-poll requires both `projects.run` and `analytics.read`; reading its input contract also needs `projects.read`. The owner's permissions, project or folder access, and connection sharing still apply. Use the endpoint's permission note for operations not listed here.

## Create and revoke a personal API key

1. Open **Settings → API Keys** in the target organization. Create a key with a recognizable application name, the required scopes, and an expiration appropriate for your rotation schedule.

![Give the key a descriptive name and set its expiration when creating it.](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/u9Tzucppc463H9hm1QfK/assets/g097-g097-02-expiration.png)

Give the key a descriptive name and set its expiration when creating it.

2. Store it securely and use it in the authentication header supported by the endpoint.
3. Review its activity and revoke it when the application no longer needs access.

The application can perform permitted operations without embedding an interactive sign-in session.

## Behavior and limitations

A key cannot grant permissions its owner lacks. Resource access and organization context still apply. Copy a newly issued secret only to secure storage; do not place it in website code or logs. Replace an expiring key before revoking the old one, then confirm the application uses the replacement.

## Related resources

API key management

Organization Roles and Permissions

[REST authentication and credential restrictions](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/authentication-and-authorization.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/identity-access-and-administration/personal-api-keys-scopes-expiration-and-revocation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
