> ## 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.

# Create and Manage API Tokens for the Springwinter API

> Generate bearer tokens to authenticate scripts, CI/CD pipelines, and automation against the Springwinter API without a browser session.

API tokens let you authenticate programmatic requests to the Springwinter API without using a browser session or CSRF cookie. Use them in CI/CD pipelines, deployment scripts, infrastructure automation, or any environment where interactive sign-in is not practical.

## Creating a Token

<Steps>
  <Step title="Open Settings → API Tokens">
    Click your organization name in the top navigation, select **Settings**, then choose **API Tokens**.
  </Step>

  <Step title="Click New Token">
    Click the **New token** button and enter a descriptive name that identifies where the token will be used — for example, `github-actions-prod` or `deploy-script-staging`.
  </Step>

  <Step title="Copy the token immediately">
    After you click **Create**, Springwinter displays the full token value exactly once. Copy it to a secure secret store right away — you cannot retrieve the value again after closing the dialog.

    Your token looks like this:

    ```
    swt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
    ```
  </Step>
</Steps>

<Warning>
  Store your token securely. It grants full organization access to the Springwinter API. If a token is compromised, revoke it immediately using the instructions below — all in-flight requests using that token will be rejected as soon as it is deleted.
</Warning>

## Using a Token

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

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

Bearer token requests skip the cookie session and CSRF check entirely, so you do not need to fetch a CSRF token first. Here is a more complete example that creates a new project:

```bash theme={null}
curl -X POST https://springwinter.dev/api/projects \
  -H "Authorization: Bearer swt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-new-project"}'
```

For use in GitHub Actions, store the token as a repository secret and reference it in your workflow:

```yaml theme={null}
- name: Redeploy web server
  run: |
    curl -X POST \
      https://springwinter.dev/api/projects/${{ vars.PROJECT_ID }}/web_servers/${{ vars.SERVER_ID }}/redeploy \
      -H "Authorization: Bearer ${{ secrets.SPRINGWINTER_TOKEN }}"
```

## Creating a Token via the API

You can also create tokens programmatically by sending a `POST` request with a `name` field:

```bash theme={null}
curl -X POST https://springwinter.dev/api/api_tokens \
  -H "Authorization: Bearer swt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{"name": "deploy-script-staging"}'
```

The response includes the token secret, which is shown only in this response and never again:

```json theme={null}
{
  "id": "tok_9z8y7x6w",
  "name": "deploy-script-staging",
  "token": "swt_9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4k3j2i1h0g9f8e7d6",
  "created_at": "2025-01-15T10:23:00Z"
}
```

## Listing Your Tokens

Send a `GET` request to retrieve all tokens for your organization. The response returns token IDs and names — never the secret values.

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

### Response fields

<ResponseField name="id" type="string">
  The unique identifier for the token. Use this ID to revoke the token.
</ResponseField>

<ResponseField name="name" type="string">
  The descriptive name you gave the token when you created it.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the token was created.
</ResponseField>

## Revoking a Token

Send a `DELETE` request with the token's ID. The token is invalidated immediately — any subsequent requests using that token receive a `401 Unauthorized` response.

```bash theme={null}
curl -X DELETE https://springwinter.dev/api/api_tokens/{id} \
  -H "Authorization: Bearer swt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"
```

<Tip>
  Use a separate token for each environment and integration — for example, one for staging, one for production CI, and one for local scripts. That way, if one token is exposed, you can revoke it without disrupting the others.
</Tip>

## Token API Reference

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/api_tokens` | List all tokens (IDs and names only) |
| `POST` | `/api/api_tokens` | Create a new token |
| `DELETE` | `/api/api_tokens/{id}` | Revoke a token by ID |