Authentication

Bearer Token (JWT)

Authenticate as a user by exchanging credentials for a short-lived JWT. Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without re-entering credentials.

1. Obtain a token

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_a1b2c3d4e5f6..."
}

curl -X POST https://api.replr.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

2. Use the token

Pass the access token in the Authorization header on every request.

curl https://api.replr.ai/v1/replrs \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

3. Refresh the token

When the access token expires (HTTP 401), exchange the refresh token for a new pair. Refresh tokens are single-use and rotate on every call.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_x9y8z7w6v5u4..."
}

curl -X POST https://api.replr.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "rt_a1b2c3d4e5f6..." }'

API Keys

API keys are long-lived credentials designed for server-to-server communication. Each key is scoped to a specific set of permissions and tied to your account. You can create keys from the settings or programmatically via the API.

Scopes

Create a key

{
  "id": "key_9f3a1b2c4d5e",
  "name": "Production backend",
  "key": "rk_live_abc123def456ghi789...",
  "scopes": ["read", "chat"],
  "created_at": "2026-03-09T12:00:00Z",
  "expires_at": null
}

curl -X POST https://api.replr.ai/v1/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "scopes": ["read", "chat"]
  }'

Use an API key

Pass the key in the X-API-Key header.

curl https://api.replr.ai/v1/replrs \
  -H "X-API-Key: rk_live_abc123def456ghi789..."

OAuth 2.0

Use the authorization code flow to let users grant your application access to their REPLR account without sharing credentials. This is the recommended approach for third-party integrations and marketplace apps.

1. Redirect the user to authorize

Send the user to the REPLR authorization page. After they approve, they will be redirected back to your redirect_uri with a code parameter.

2. Exchange code for tokens

Once the user is redirected back with a code, exchange it for an access token on your backend. The authorization code is single-use and expires after 10 minutes.

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_oauth_m4n5o6p7...",
  "scope": "read chat"
}

curl -X POST https://api.replr.ai/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "ac_xyz789...",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

3. Refresh an OAuth token

OAuth access tokens expire after 1 hour. Use the refresh token exactly as described in the Bearer Token section above. Include your client_id and client_secret in the refresh request body for OAuth tokens.

Error Responses

Authentication failures return standard JSON error objects. The two status codes you will encounter are:

// 401 Unauthorized — missing or invalid credentials
{
  "error": "unauthorized",
  "message": "Invalid or expired access token."
}

// 403 Forbidden — valid credentials, insufficient permissions
{
  "error": "forbidden",
  "message": "This API key does not have the \"admin\" scope required for this action."
}

Security Best Practices