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

# Authenticate with the Shootbin API

> Learn how to create API tokens, attach them to requests, understand token scopes, and handle authentication errors from the Shootbin API.

The Shootbin API uses token-based authentication. Every request must carry a valid Bearer token in the `Authorization` header. Tokens are tied to your user account and carry fine-grained scopes that control which operations they can perform.

<Warning>
  API access is available on the **Agency plan only**. Tokens issued on Hobby or Studio accounts will receive a `403` response on all API endpoints, regardless of scope.
</Warning>

## Creating an API token

1. Log in to your Shootbin account.
2. Open **Account Settings** and navigate to the **API Tokens** section.
3. Give the token a descriptive name (e.g. `ci-uploader` or `integration-prod`).
4. Select the scopes the token needs (see [Token scopes](#token-scopes) below).
5. Click **Create** and copy the token immediately, it is only shown once.

Store the token securely (for example in a secrets manager or CI/CD environment variable). Treat it like a password: anyone with the token can act on your behalf.

## Attaching the token to requests

Include the token in every request using the `Authorization` header alongside `Accept: application/json`:

```bash theme={null}
curl -X GET https://your-shootbin-domain.com/api/projects \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
```

The `Accept: application/json` header is required. Without it, the API may return an HTML redirect to the login page on authentication failures instead of a JSON error.

<Tip>
  When using environment variables, store your token as `SHOOTBIN_API_TOKEN` and reference it as `$SHOOTBIN_API_TOKEN` in shell scripts to avoid leaking the value in your shell history.
</Tip>

## Token scopes

When you create a token, you assign it one or more scopes. The API enforces these scopes on every request:

| Scope    | Alias         | What it allows                                                        |
| -------- | ------------- | --------------------------------------------------------------------- |
| `create` | `post:create` | Create projects, albums, and upload photos                            |
| `update` | `post:update` | Approve/unapprove photos, add or delete annotations, upload revisions |

A token without the `create` scope will receive a `403` when it attempts to create a project or upload a photo. A token without `update` will receive a `403` when it tries to approve a photo or manage annotations.

<Note>
  You can issue multiple tokens with different scopes, for example a read-only reporting token and a separate upload token used in your editing pipeline.
</Note>

## Authentication errors

| Status             | Cause                                                                                 | Resolution                                                                      |
| ------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `401 Unauthorized` | Token is missing, malformed, or has been revoked                                      | Check that the `Authorization: Bearer` header is present and the token is valid |
| `403 Forbidden`    | Token is valid but lacks the required scope, or the account is not on the Agency plan | Verify the token's scopes in account settings, or upgrade your plan             |

Example `401` response:

```json theme={null}
{
  "message": "Unauthenticated."
}
```

Example `403` response when scope is missing:

```json theme={null}
{
  "message": "This API token does not have permission to create projects."
}
```

## Revoking a token

You can revoke any token from the **API Tokens** section of your account settings. Revoked tokens return `401` immediately on subsequent requests. Rotate tokens regularly and revoke any that are no longer needed.