Authentication

The SilentChat API supports two authentication methods: JWT bearer tokens for user-based access and API keys for server-to-server integrations.

JWT Bearer Tokens

JWT tokens are the primary authentication method for users interacting with the API. You obtain tokens by logging in through the /v1/auth/login endpoint.

Obtaining Tokens

Send a POST request to the login endpoint with your credentials:

POST /v1/auth/login HTTP/1.1
Host: api.silentchat.de
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

A successful response returns an access token and a refresh token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "token_type": "Bearer",
  "expires_in": 900
}

Using the Access Token

Include the access token in the Authorization header of every API request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Access tokens expire after 15 minutes. When a token expires the API responds with 401 Unauthorized.

Refreshing Tokens

Before or after the access token expires, exchange the refresh token for a new access token:

POST /v1/auth/refresh HTTP/1.1
Host: api.silentchat.de
Content-Type: application/json

{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
}

The response has the same shape as the login response.

Refresh tokens are single-use. Each refresh request returns a new refresh token and invalidates the previous one. Refresh tokens expire after 30 days.

Token Refresh Flow

1. Make an API request with the current access token.
2. If the response is 401 Unauthorized, call /v1/auth/refresh with your stored refresh token.
3. Store the new access token and refresh token from the response.
4. Retry the original request with the new access token.
5. If the refresh also fails with 401, the user must log in again.

API Key Authentication

For server-to-server integrations, you can authenticate using an API key instead of JWT tokens. API keys are long-lived and do not expire automatically.

Creating an API Key

1. Go to Settings → API Keys in the dashboard.
2. Click Create API Key.
3. Give the key a descriptive name and choose the permissions scope.
4. Copy the key immediately — it will not be shown again.

Using the API Key

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

X-API-Key: sk_live_abc123def456...

When using an API key you must also include the X-Tenant-ID header to specify which tenant the request is scoped to:

GET /v1/conversations HTTP/1.1
Host: api.silentchat.de
X-API-Key: sk_live_abc123def456...
X-Tenant-ID: tn_abc123
Content-Type: application/json

Security Best Practices

• Never expose API keys in client-side code. API keys should only be used on your server.
• Store tokens and keys in environment variables or a secret manager, not in source code.
• Rotate API keys periodically and revoke any that may have been compromised.
• Use the narrowest permissions scope possible when creating API keys.
• Always use HTTPS. The API will reject plain HTTP requests.