API Tokens

API tokens are used to authenticate your requests to the Bouncer API. Each organization can create multiple tokens for different applications or environments.

Creating a Token

Via Dashboard

1. Log in to your Bouncer dashboard
2. Navigate to Settings > Organization
3. Scroll to the API Tokens section
4. Click Create Token
5. Enter a name for your token (e.g., "Production API", "Development")
6. Click Create

Token Format

Tokens are generated using Laravel Sanctum and follow this format:

1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

The number before the pipe (|) is the token ID, and the string after is the actual secret.

Using Tokens

Include the token in the Authorization header of your API requests:

curl https://your-bouncer-instance.com/api/v2/session \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example with Different Languages

curl -X POST https://your-bouncer-instance.com/api/v2/session \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"age_target": 18, "redirect_url": "https://example.com/callback"}'

const response = await fetch('https://your-bouncer-instance.com/api/v2/session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer 1|abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    age_target: 18,
    redirect_url: 'https://example.com/callback',
  }),
});

const data = await response.json();

$client = new GuzzleHttp\Client();

$response = $client->post('https://your-bouncer-instance.com/api/v2/session', [
    'headers' => [
        'Authorization' => 'Bearer 1|abc123...',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'age_target' => 18,
        'redirect_url' => 'https://example.com/callback',
    ],
]);

$data = json_decode($response->getBody(), true);

import requests

response = requests.post(
    'https://your-bouncer-instance.com/api/v2/session',
    headers={
        'Authorization': 'Bearer 1|abc123...',
        'Content-Type': 'application/json',
    },
    json={
        'age_target': 18,
        'redirect_url': 'https://example.com/callback',
    }
)

data = response.json()

Managing Tokens

Viewing Tokens

In the dashboard, you can view:

• Token name
• Creation date
• Last used timestamp

Revoking Tokens

To revoke a token:

1. Go to Settings > Organization
2. Find the token in the API Tokens section
3. Click the Revoke button
4. Confirm the revocation

Security Best Practices

Token Storage

• Never commit tokens to version control
• Use environment variables to store tokens
• Use a secrets manager in production (AWS Secrets Manager, HashiCorp Vault, etc.)

# .env file (never commit this!)
BOUNCER_API_TOKEN=1|abc123...

Token Rotation

Regularly rotate your tokens:

1. Create a new token
2. Update your applications to use the new token
3. Verify everything works
4. Revoke the old token

Separate Environments

Create separate tokens for:

• Development
• Staging
• Production

This allows you to revoke compromised tokens without affecting other environments.

Error Responses

401 Unauthenticated

{
  "message": "Unauthenticated."
}

This error occurs when:

• No token is provided
• The token is invalid
• The token has been revoked

Troubleshooting

1. Verify the token is correctly formatted
2. Ensure the Authorization header uses Bearer prefix
3. Check if the token has been revoked
4. Confirm you're using the correct Bouncer instance URL