Authentication overview

Reqon supports multiple authentication methods for connecting to APIs. Authentication is configured at the source level and credentials are provided via CLI or configuration files.

Supported auth types

Type	Description	Use Case
none	No authentication	Public APIs
bearer	Bearer token	Most REST APIs
basic	HTTP basic auth	Legacy systems
api_key	API key in a header or query parameter	Many SaaS APIs
oauth2	OAuth 2.0 with refresh	Enterprise APIs

:::note Missing credentials fail loudly All five types attach credentials at runtime. An auth type configured without the credentials it needs throws when the source is initialized, rather than sending the request unauthenticated, so a typo in an env var name fails the run instead of producing a wall of 401s. :::

The auth: value in a source block is only the type. Credentials are never written inline in the source block. They come from a --auth <file> JSON file keyed by source name, or from REQON_{SOURCE}_{FIELD} environment variables.

Quick start

In mission file

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

Credentials file

Create credentials.json:

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

Run with credentials

reqon mission.vague --auth ./credentials.json

Credential sources

File-based

reqon mission.vague --auth ./credentials.json

Environment variables

Reference in credentials:

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

The ${VAR} reference also supports a default with ${VAR:-fallback}. A reference with no value and no default throws rather than sending an empty credential.

Auto-discovered environment variables

You don't need a credentials file at all. Reqon looks for variables named REQON_{SOURCE}_{FIELD}, where {SOURCE} is the uppercased source name. For a source named API:

export REQON_API_TYPE="bearer"
export REQON_API_TOKEN="your-token"
reqon mission.vague

Recognized fields are TYPE, TOKEN, ACCESS_TOKEN, REFRESH_TOKEN, TOKEN_ENDPOINT, CLIENT_ID, CLIENT_SECRET, API_KEY, HEADER_NAME, USERNAME, and PASSWORD. If a token is set without a type, the type defaults to bearer.

Programmatic

import { execute } from 'reqon-dsl';

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

Multiple sources

Handle multiple APIs with different auth:

mission MultiSource {
  source Xero {
    auth: oauth2,
    base: "https://api.xero.com/api.xro/2.0"
  }

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

  source Legacy {
    auth: basic,
    base: "https://legacy.example.com"
  }
}

Credentials file:

{
  "Xero": {
    "type": "oauth2",
    "clientId": "...",
    "clientSecret": "...",
    "accessToken": "...",
    "refreshToken": "...",
    "tokenEndpoint": "https://identity.xero.com/connect/token"
  },
  "Stripe": {
    "type": "bearer",
    "token": "sk_live_..."
  },
  "Legacy": {
    "type": "basic",
    "username": "admin",
    "password": "secret"
  }
}

Refreshing tokens

For oauth2 sources, Reqon refreshes the access token when a request comes back with a 401. It posts to tokenEndpoint with the refresh token, then retries the request once with the new token:

{
  "Xero": {
    "type": "oauth2",
    "accessToken": "current-token",
    "refreshToken": "refresh-token",
    "tokenEndpoint": "https://identity.xero.com/connect/token",
    "clientId": "...",
    "clientSecret": "..."
  }
}

The refreshed token is held in memory for the rest of the run. It is not written back to the credentials file, so the next run starts from the original accessToken again.

Bearer tokens are not refreshed. If a bearer token expires, the request fails and you'll need to update the credentials.

Security best practices

:::danger Never Commit Credentials Always add credential files to .gitignore before committing. Exposed API tokens can lead to unauthorized access and data breaches. :::

Never commit credentials

Add to .gitignore:

credentials.json
.env
*.pem
*.key

Use environment variables

export API_TOKEN="your-token"
reqon mission.vague

Rotate tokens regularly

For OAuth2, ensure refresh tokens are valid.

:::tip Use environment variables Store credentials in environment variables for local development and use secret management services (AWS Secrets Manager, HashiCorp Vault) in production. :::

Use least privilege

Request only the scopes you need when you generate the token with the provider. Reqon sends whatever access token you give it, so scoping happens on the provider's side.

Troubleshooting

Authentication failed

1. Check the credentials file path.
2. Verify the token is valid.
3. Check the source name matches the credentials key.

Token expired

For OAuth2, ensure:

• refreshToken is present.
• tokenEndpoint is correct.
• The token hasn't been revoked.

Wrong auth type

Match the type in credentials to mission:

// Mission says bearer
source API { auth: bearer, base: "..." }

// Credentials must also be bearer
{
  "API": {
    "type": "bearer",  // Must match
    "token": "..."
  }
}