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

You need the Owner or Admin role in the organization. Managers and members can see the token list, but they cannot create or revoke tokens.

1. Log in to your Bouncer dashboard at app.bouncer.digital
2. Click your name at the bottom of the sidebar (on a phone, in the top bar) and choose Organization
3. Scroll to the API Tokens section
4. Type a Token Name (e.g., "Production API", "Development")
5. Click Create Token
6. Copy the token from the API Token Created window, then click Done

If your account belongs to more than one organization, the Organization page always works on the organization named under Organization Information, which may not be the one selected in the sidebar. Check that name before you create or revoke a token.

Token Format

Tokens are generated using Laravel Sanctum and follow this format:

1|abc123...

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, with the Bearer scheme, and send Accept: application/json on every request:

curl https://app.bouncer.digital/api/v2/session/SESSION_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Example with Different Languages

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

const response = await fetch('https://app.bouncer.digital/api/v2/session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer 1|abc123...',
    'Accept': 'application/json',
    '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://app.bouncer.digital/api/v2/session', [
    'headers' => [
        'Authorization' => 'Bearer 1|abc123...',
        'Accept' => 'application/json',
        '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://app.bouncer.digital/api/v2/session',
    headers={
        'Authorization': 'Bearer 1|abc123...',
        'Accept': 'application/json',
        'Content-Type': 'application/json',
    },
    json={
        'age_target': 18,
        'redirect_url': 'https://example.com/callback',
    }
)

data = response.json()

Managing Tokens

Viewing Tokens

In the Existing Tokens list of the API Tokens section, you can view:

• Token name
• When it was created
• When it was last used, or Never used

Revoking Tokens

To revoke a token (you need the Owner or Admin role):

1. Click your name in the sidebar and choose Organization
2. Find the token in the Existing Tokens list of the API Tokens section
3. Click the trash icon on the token's row
4. In the Revoke API token? window, click Revoke

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.)
• Call the API from your server only: a token placed in browser JavaScript or in a mobile app can be copied and used by anyone

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

Token Rotation

Tokens do not expire, so rotate them regularly:

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.

Bouncer has no separate test mode. Every token, whatever its name, creates real sessions in your organization, and they appear in Verifications and Analytics.

Error Responses

401 Unauthenticated

{
  "message": "Unauthenticated."
}

This error occurs when:

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

You get this JSON response when the request sends Accept: application/json. Without that header, Bouncer answers with a 302 redirect to the dashboard login page, and an HTTP client that follows redirects may show you the HTML of the login page with a 200.

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 calling https://app.bouncer.digital
5. If you get HTML or a redirect instead of JSON, add the Accept: application/json header