Authentication

The REPLR API supports three authentication methods. Choose the one that fits your use-case: Bearer tokens for user sessions, API keys for server-to-server calls, and OAuth 2.0 for third-party integrations.

Base URL

https://api.replr.ai/v1

Bearer Token

Short-lived JWTs for user sessions. Obtained via login.

API Key

Long-lived keys with scoped permissions for backends.

OAuth 2.0

Authorization code flow for third-party apps.

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

POST/v1/auth/login

Exchange email and password for an access token and refresh token.

Request Body

Name	Type	Required	Description
`email`	string	Required	Account email address.
`password`	string	Required	Account password.

Response

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

Examples

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.

POST/v1/auth/refresh

Exchange a refresh token for a new access token and refresh token.

Request Body

Name	Type	Required	Description
`refresh_token`	string	Required	The refresh token returned from login or a previous refresh.

Response

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

Examples

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 dashboard or programmatically via the API.

Scopes

Scope	Permissions
`read`	List and retrieve characters, conversations, messages, and account info.
`chat`	Send messages, create conversations, and interact with characters.
`admin`	Create and delete characters, manage API keys, configure webhooks, and access billing.

Create a key

POST/v1/api-keysAuth Required

Create a new API key with the specified scopes.

Request Body

Name	Type	Required	Description
`name`	string	Required	A human-readable label for this key.
`scopes`	string[]	Required	Permissions granted to the key. One or more of "read", "chat", "admin".
`expires_in_days`	number	Optional	Days until expiry. Omit for a non-expiring key.

Response

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

Examples

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.

Authorization URL

https://api.replr.ai/v1/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&scope=read%20chat&state=random_csrf_token

Query Parameters

Name	Type	Required	Description
`response_type`	string	Required	Must be "code".
`client_id`	string	Required	Your application client ID.
`redirect_uri`	string	Required	URI to redirect the user back to after authorization.
`scope`	string	Required	Space-separated scopes, e.g. "read chat".
`state`	string	Required	An opaque CSRF-prevention value your app generates.

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.

POST/v1/oauth/token

Exchange an authorization code for access and refresh tokens.

Request Body

Name	Type	Required	Description
`grant_type`	string	Required	Must be "authorization_code".
`code`	string	Required	The authorization code from the redirect.
`redirect_uri`	string	Required	Must match the URI used in the authorize request.
`client_id`	string	Required	Your application client ID.
`client_secret`	string	Required	Your application client secret.

Response

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

Examples

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:

Status	Error	Meaning
`401`	unauthorized	Missing, malformed, or expired credentials. Re-authenticate or refresh the token.
`403`	forbidden	Valid credentials but insufficient permissions. Check that your API key includes the required scope.

// 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

Treat all tokens and API keys as secrets. A leaked credential gives full access to the associated scopes until revoked.

•Store tokens server-side. Never expose access tokens, refresh tokens, or API keys in client-side code, URLs, or version control.
•Rotate API keys regularly. Create a new key, migrate your services, then revoke the old one. Use the expires_in_days parameter to enforce automatic expiry.
•Use minimal scopes. Only request the scopes your application actually needs. A read-only dashboard should not have the admin scope.
•Validate the state parameter in OAuth. Always verify the state value returned from the authorization redirect matches the one you generated to prevent CSRF attacks.
•Handle token refresh proactively. Refresh access tokens before they expire rather than waiting for a 401 response to avoid interruptions in your application flow.
•Use HTTPS exclusively. All REPLR API endpoints require TLS. Never send credentials over unencrypted connections.

← Quick Start API Reference →

Authentication

Base URL

https://api.replr.ai/v1

Bearer Token

Short-lived JWTs for user sessions. Obtained via login.

API Key

Long-lived keys with scoped permissions for backends.

OAuth 2.0

Authorization code flow for third-party apps.

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

POST/v1/auth/login

Exchange email and password for an access token and refresh token.

Request Body

Name	Type	Required	Description
`email`	string	Required	Account email address.
`password`	string	Required	Account password.

Response

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

Examples

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.

POST/v1/auth/refresh

Exchange a refresh token for a new access token and refresh token.

Request Body

Name	Type	Required	Description
`refresh_token`	string	Required	The refresh token returned from login or a previous refresh.

Response

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

Examples

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

API Keys

Scopes

Scope	Permissions
`read`	List and retrieve characters, conversations, messages, and account info.
`chat`	Send messages, create conversations, and interact with characters.
`admin`	Create and delete characters, manage API keys, configure webhooks, and access billing.

Create a key

POST/v1/api-keysAuth Required

Create a new API key with the specified scopes.

Request Body

Name	Type	Required	Description
`name`	string	Required	A human-readable label for this key.
`scopes`	string[]	Required	Permissions granted to the key. One or more of "read", "chat", "admin".
`expires_in_days`	number	Optional	Days until expiry. Omit for a non-expiring key.

Response

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

Examples

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

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.

Authorization URL

https://api.replr.ai/v1/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&scope=read%20chat&state=random_csrf_token

Query Parameters

Name	Type	Required	Description
`response_type`	string	Required	Must be "code".
`client_id`	string	Required	Your application client ID.
`redirect_uri`	string	Required	URI to redirect the user back to after authorization.
`scope`	string	Required	Space-separated scopes, e.g. "read chat".
`state`	string	Required	An opaque CSRF-prevention value your app generates.

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.

POST/v1/oauth/token

Exchange an authorization code for access and refresh tokens.

Request Body

Name	Type	Required	Description
`grant_type`	string	Required	Must be "authorization_code".
`code`	string	Required	The authorization code from the redirect.
`redirect_uri`	string	Required	Must match the URI used in the authorize request.
`client_id`	string	Required	Your application client ID.
`client_secret`	string	Required	Your application client secret.

Response

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

Examples

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

Error Responses

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

Status	Error	Meaning
`401`	unauthorized	Missing, malformed, or expired credentials. Re-authenticate or refresh the token.
`403`	forbidden	Valid credentials but insufficient permissions. Check that your API key includes the required scope.

// 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

Treat all tokens and API keys as secrets. A leaked credential gives full access to the associated scopes until revoked.

•Store tokens server-side. Never expose access tokens, refresh tokens, or API keys in client-side code, URLs, or version control.
•Rotate API keys regularly. Create a new key, migrate your services, then revoke the old one. Use the expires_in_days parameter to enforce automatic expiry.
•Use minimal scopes. Only request the scopes your application actually needs. A read-only dashboard should not have the admin scope.
•Validate the state parameter in OAuth. Always verify the state value returned from the authorization redirect matches the one you generated to prevent CSRF attacks.
•Handle token refresh proactively. Refresh access tokens before they expire rather than waiting for a 401 response to avoid interruptions in your application flow.
•Use HTTPS exclusively. All REPLR API endpoints require TLS. Never send credentials over unencrypted connections.

← Quick Start API Reference →