Authentication

The Connexease API supports two authentication methods:

1. Account Access Tokens (recommended) — long-lived tokens sent with the Bearer scheme. Suitable for server-to-server integrations.
2. JWT Tokens (legacy) — short-lived (24h) tokens obtained with a username/password exchange and sent with the JWT scheme. Still supported for backward compatibility.

Both schemes are passed via the Authorization HTTP header. Keep every token secret — do not commit them to source control, embed them in client-side code, or share them in publicly accessible channels.

Account Access Tokens (recommended)

Account Access Tokens are the preferred way to authenticate against the Connexease API. Unlike JWTs, they are not tied to a user's password and do not need to be refreshed every 24 hours, which makes them well-suited for backend integrations and long-running services.

Using an Account Access Token

Include the token in the Authorization header using the Bearer scheme:

GET /some/endpoint/ HTTP/1.1
Host: api.connexease.com
Authorization: Bearer <your_account_access_token>
Accept: application/json

Obtaining a token

Account Access Tokens are issued by the Connexease support team. Contact support to request a token for your account; they will provide the token value to you directly.

⚠️ Security

• Treat Account Access Tokens like passwords. Store them in a secrets manager, not in source code.
• Rotate tokens periodically and immediately contact support to revoke any token you suspect has been exposed.

Legacy JWT Tokens

Authenticate your account by including your JWT key in API requests. API usernames and passwords used to obtain JWTs are issued by the Connexease support team — contact support to request credentials for your account. You can create your JWT keys by using JWT /jwt/ endpoint. Your JWT keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

The token generated has a validity period of 24 hours. It is advisable to cache or store the token and utilize it until its expiry.

Important: There is a daily limit of 30 token generations per API user. Exceeding this limit will result in the API User being banned. Reactivation requires intervention from the support team.

Using a JWT token

JWT tokens are sent with the JWT scheme (not Bearer):

GET /some/endpoint/ HTTP/1.1
Host: api.connexease.com
Authorization: JWT <your_jwt_token>
Accept: application/json

Getting JWTs

POST /jwt/

Creates JSON Web Token to authenticate yourself on API endpoints.

Status Codes:

• 200 OK – no error, JWT created
• 400 Bad Request – there's no user

⚠️ Note: Do not retry 4XX responses. These are client errors and will not be resolved by retrying the same request.

Example request:

POST /jwt/ HTTP/1.1
Host: api.connexease.com
Accept: application/json

{
    "username": "john.doe",
    "password": "awesomepassword"
}

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token": "awesomejwttoken",
    "account": {
        "uuid": "c7617c90-0eef-4c75-b604-bdfbc152437c"
    },
    "otp": false,
    "client": {
        "device_id": "deviceId"
    }
}

Example failure responses:

400 — Missing or Invalid username

{"message": "Username is required."}

403 — Agent is banned

{"message": "This agent has been banned!"}

403 — Account is inactive

401 — Wrong password

{"detail": "No active account found with the given credentials"}

Choosing between the two

New integrations should use Account Access Tokens. JWTs remain supported for backward compatibility, but we recommend migrating when convenient.