Authentication

The Bassode API uses a two-layer authentication model. Every request must carry a valid API key (Layer 1). User-sensitive endpoints additionally require a JWT bearer token (Layer 2).

Layer 1 — API Key

All requests must include both headers:

X-Api-Key — Your public API key (starts with bsk_live_)
X-Api-Secret — Your API secret

The API key identifies your application and determines which scopes (endpoints) it can access.

Request with API Key Only

GET /api/Dac HTTP/1.1
Host: api.bassode.com
X-Api-Key: bsk_live_xxxxxxxxxxxxxx
X-Api-Secret: your_secret_here

Layer 2 — JWT Bearer Token

Endpoints that involve user data additionally require an Authorization: Bearer header containing a signed JWT. The JWT identifies the logged-in user on whose behalf the call is made and carries their role and subscription status.

Obtaining a JWT

Authenticate a user with POST /api/Users/Login:

POST /api/Users/Login HTTP/1.1
Host: api.bassode.com
X-Api-Key: bsk_live_xxxxxxxxxxxxxx
X-Api-Secret: your_secret_here
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "userpassword"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-04-26T12:00:00Z",
  "user": {
    "id": 42,
    "email": "user@example.com",
    "role": 1,
    "isTrialSubscription": false
  }
}

Using the JWT

Include the token in all subsequent requests that require user identity:

GET /api/ApiKeys HTTP/1.1
Host: api.bassode.com
X-Api-Key: bsk_live_xxxxxxxxxxxxxx
X-Api-Secret: your_secret_here
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT Claims

The JWT payload contains the following claims:

Claim	Description
`sub`	User ID
`email`	User email address
`role`	Effective role (0=Free, 1=Subscriber, 2=Admin, 3=SuperAdmin)
`plan_type`	Subscription plan type (0=Free, 1=Monthly, 2=Yearly, 3=Lifetime)
`trial_expires_at`	Unix timestamp of trial expiry — only present for trial users

Trial users: A user on an active trial receives role=1 (Subscriber) in the JWT even if their account role is Free. Once the trial expires, the role is automatically downgraded to Free on the next request — no re-login required.

Subscription Requirement

Creating and managing API keys requires an active subscription (role >= Subscriber). To obtain a Subscriber role your users must have an active paid plan or an active trial. You can create subscriptions via POST /api/Subscriptions after the user is logged in.

API Key Format

bsk_live_2iqblig9bj8ah3154hnald6zqe6ioge6
 │   │    │
 │   │    └── Unique identifier
 │   └──────── Environment (live / test)
 └──────────── Prefix (Bassode Service Key)

Error Responses

Missing or invalid API key

HTTP/1.1 401 Unauthorized

{
  "error": "Missing authentication headers",
  "message": "Both X-Api-Key and X-Api-Secret headers are required"
}

Insufficient scope

HTTP/1.1 403 Forbidden

{
  "error": "Insufficient permissions",
  "message": "Your API key does not have the required scope"
}

Missing or insufficient JWT

HTTP/1.1 403 Forbidden

{
  "error": "Insufficient permissions",
  "message": "A valid user JWT with sufficient role is required"
}

Security Best Practices

Store secrets in environment variables — never hardcode them in source code
Store JWTs securely — use encrypted storage; never expose them in client-side JavaScript
Use minimal scopes — only request the scopes your application needs
Rotate keys periodically — revoke old keys and create new ones regularly
HTTPS only — all requests must use HTTPS

Next Steps

Learn about Scopes Explore Endpoints