> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Tokens API: Create and Revoke Access Tokens

> REST endpoints to list, create, and revoke organization-scoped bearer tokens for programmatic and CI/CD access to the Springwinter API.

API tokens are organization-scoped credentials for programmatic access to Springwinter. Every member of an organization shares access to the same token list, so tokens you create are visible to teammates and vice versa. You can manage tokens through the dashboard at **Settings → API Tokens**, or through the endpoints documented here. Authenticate requests by passing the token in an `Authorization: Bearer` header — no session cookie or CSRF token is needed.

## List API Tokens

**GET /api/api\_tokens**

Return all API tokens that have been created for your organization. Secret values are never included in list or get responses — only the token ID, name, and creation timestamp.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/api_tokens \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "api_tokens": [
      {
        "id": "tok_aabb1122",
        "name": "ci-deploy",
        "created_at": "2025-01-10T09:15:00Z"
      },
      {
        "id": "tok_ccdd3344",
        "name": "staging-monitor",
        "created_at": "2025-01-12T14:30:00Z"
      }
    ]
  }
  ```
</CodeGroup>

<ResponseField name="api_tokens" type="array">
  Array of token summary objects. The `token` secret field is never returned here.

  <Expandable title="Token object fields">
    <ResponseField name="id" type="string">Unique identifier for the token. Use this when deleting.</ResponseField>
    <ResponseField name="name" type="string">Human-readable label assigned at creation.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 timestamp of when the token was created.</ResponseField>
  </Expandable>
</ResponseField>

***

## Create an API Token

**POST /api/api\_tokens**

Create a new API token. The full secret value is returned **only in this response** — Springwinter does not store the plaintext token and cannot show it again.

<Warning>
  The token secret is returned only in the `POST /api/api_tokens` response. Springwinter cannot retrieve it again after this call. Store it securely in a secrets manager, CI/CD environment variable, or password vault immediately. If you lose the secret, delete the token and create a new one.
</Warning>

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://springwinter.dev/api/api_tokens \
    -H "Authorization: Bearer swt_yourtoken" \
    -H "Content-Type: application/json" \
    -d '{ "name": "ci-deploy" }'
  ```

  ```json Response (201 Created) theme={null}
  {
    "id": "tok_aabb1122",
    "name": "ci-deploy",
    "token": "swt_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2025-01-10T09:15:00Z"
  }
  ```
</CodeGroup>

<ParamField body="name" type="string" required>
  A descriptive label for the token. Choose a name that identifies its purpose or owner, for example `ci-deploy`, `terraform-prod`, or `monitoring-script`.
</ParamField>

<ResponseField name="id" type="string">Unique token identifier. Store this alongside the secret for revocation purposes.</ResponseField>
<ResponseField name="name" type="string">The label you provided.</ResponseField>

<ResponseField name="token" type="string">
  The full bearer token secret. Begins with `swt_`. This value is returned **once only** — copy it to a secrets manager immediately.
</ResponseField>

<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>

***

## Revoke an API Token

**DELETE /api/api\_tokens/{id}**

Permanently revoke an API token. Any request using the revoked token will receive a `401 Unauthorized` response immediately after deletion.

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE https://springwinter.dev/api/api_tokens/tok_aabb1122 \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response (200 OK) theme={null}
  {
    "id": "tok_aabb1122",
    "deleted": true
  }
  ```
</CodeGroup>

<ParamField path="id" type="string" required>
  The ID of the token to revoke. Retrieve the ID from the `GET /api/api_tokens` response.
</ParamField>

***

## Using Tokens in Requests

Pass the token in the `Authorization` header on every API request:

```bash theme={null}
curl https://springwinter.dev/api/projects \
  -H "Authorization: Bearer swt_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

<Tip>
  In GitHub Actions, store the token as a repository secret (`SPRINGWINTER_TOKEN`) and reference it with `${{ secrets.SPRINGWINTER_TOKEN }}`. Never hard-code the token in source files or commit it to version control.
</Tip>

<Accordion title="Token security best practices">
  * **Use one token per system.** Create a dedicated token for each CI/CD pipeline, script, or integration so you can revoke individual access without affecting others.
  * **Rotate tokens regularly.** Create a replacement before revoking the old token to avoid downtime.
  * **Prefer least privilege.** Tokens inherit full organization-level API access. Limit where tokens are stored and who can read them.
  * **Audit periodically.** Review the token list in **Settings → API Tokens** and delete any tokens that are no longer in use.
</Accordion>