SilentChat

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": "jane@example.com",
  "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..."
}

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. Client makes an API request with the access token.
  2. Server returns 401 Unauthorized because the token has expired.
  3. Client sends the refresh token to POST /v1/auth/refresh.
  4. Server returns a new access token and a new refresh token.
  5. Client retries the original request with the new access token.

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. In the dashboard, go to Settings → API Keys.
  2. Click New API Key and give it a descriptive name (e.g. Production Backend).
  3. Choose the scopes (permissions) the key should have.
  4. Click Create and 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 your API key or refresh token in client-side code or public repositories.
  • Store secrets in environment variables or a secrets manager, never in source code.
  • Use the minimum required scopes when creating API keys.
  • Rotate API keys regularly and revoke any that may have been compromised.
  • Always use HTTPS — never send tokens over plain HTTP.
API authentication | SilentChat