Skip to main content

Bearer token authentication

Bearer token authentication is the most common auth method for REST APIs. The token is sent in the Authorization header with each request.

Configuration​

Mission file​

source API {
  auth: bearer,
  base: "https://api.example.com"
}

Credentials file​

{
  "API": {
    "type": "bearer",
    "token": "your-api-token"
  }
}

How it works​

Reqon adds the token to every request:

GET /api/users HTTP/1.1
Host: api.example.com
Authorization: Bearer your-api-token

Credential options​

FieldRequiredDescription
typeYesMust be "bearer"
tokenYesThe bearer token

Environment variables​

In credentials file​

{
  "API": {
    "type": "bearer",
    "token": "${API_TOKEN}"
  }
}

Then set the environment variable:

export API_TOKEN="your-token"
reqon mission.vague --auth credentials.json

In mission file​

source API {
  auth: bearer,
  base: "https://api.example.com",
  token: env("API_TOKEN")
}

Common use cases​

GitHub API​

source GitHub {
  auth: bearer,
  base: "https://api.github.com"
}
{
  "GitHub": {
    "type": "bearer",
    "token": "ghp_xxxxxxxxxxxxxxxxxxxx"
  }
}

Stripe API​

source Stripe {
  auth: bearer,
  base: "https://api.stripe.com/v1"
}
{
  "Stripe": {
    "type": "bearer",
    "token": "sk_live_xxxxxxxxxxxxxxxxxxxx"
  }
}

Custom API​

source CustomAPI {
  auth: bearer,
  base: "https://api.mycompany.com/v1"
}
{
  "CustomAPI": {
    "type": "bearer",
    "token": "your-custom-token"
  }
}

Token rotation​

Manual rotation​

  1. Generate new token in API provider
  2. Update credentials file
  3. Run mission

Programmatic rotation​

import { execute } from 'reqon';

const token = await fetchNewToken(); // Your logic

await execute(source, {
  auth: {
    API: {
      type: 'bearer',
      token
    }
  }
});

Handling expiration​

Bearer tokens may expire. Handle with match:

action FetchData {
  get "/data"

  match response {
    { error: _, code: 401 } -> abort "Token expired - please update credentials",
    _ -> continue
  }
}

Or with token refresh:

action FetchData {
  get "/data"

  match response {
    { error: _, code: 401 } -> jump RefreshToken then retry,
    _ -> continue
  }
}

action RefreshToken {
  post "/auth/token" {
    body: { apiKey: env("API_KEY") }
  }
  // Response contains new token
}

Multiple tokens​

For APIs requiring different tokens per endpoint:

source ReadAPI {
  auth: bearer,
  base: "https://api.example.com"
}

source WriteAPI {
  auth: bearer,
  base: "https://api.example.com"
}
{
  "ReadAPI": {
    "type": "bearer",
    "token": "read-only-token"
  },
  "WriteAPI": {
    "type": "bearer",
    "token": "write-token"
  }
}

Security best practices​

Store tokens securely​

# Never commit tokens
echo "credentials.json" >> .gitignore

Use environment variables​

export API_TOKEN=$(cat ~/.secrets/api-token)

Rotate regularly​

Set up periodic token rotation in your CI/CD pipeline.

Use minimal scopes​

If the API supports scoped tokens, use the minimum required permissions.

Troubleshooting​

"401 Unauthorized"​

  1. Check token is correct
  2. Check token hasn't expired
  3. Verify token has required permissions

"Invalid token format"​

Ensure token doesn't have extra whitespace:

{
  "API": {
    "type": "bearer",
    "token": "your-token"  // No leading/trailing spaces
  }
}

Token not being sent​

Verify source name matches:

source MyAPI { auth: bearer }  // Name: MyAPI
{
  "MyAPI": {  // Must match exactly
    "type": "bearer",
    "token": "..."
  }
}