Authentication overview

How to authenticate with the CREDEBL Platform API using Bearer JWT tokens.

The CREDEBL Platform API uses JSON Web Tokens (JWT) for authentication. Every protected endpoint requires a valid Bearer token in the Authorization header.

Base URL

http://localhost:5000/api

In production, replace localhost:5000 with your configured API_GATEWAY_HOST and API_GATEWAY_PORT.

Getting started

1. Register your account

   Send your email to POST /auth/verification-mail. The platform sends a verification code to that address.

2. Verify your email

   Call GET /auth/verify with your email and the verification code you received.

3. Complete your profile

   Submit your name, password, and other details to POST /auth/signup.

4. Sign in

   Call POST /auth/signin with your email and password. The response contains an access_token and a refresh_token.

5. Call protected endpoints

   Include the access_token in every subsequent request as a Bearer token.

   curl -H "Authorization: Bearer <your-jwt-token>" \
     http://localhost:5000/v1/orgs
   

Including the token in requests

Pass the JWT in the Authorization header using the Bearer scheme.

curl

curl --request GET \
  --url http://localhost:5000/v1/orgs \
  --header "Authorization: Bearer <your-jwt-token>"

Token format and expiry

Tokens are standard JWTs signed with RS256. The expires_in field in the sign-in response indicates how many seconds until the token expires (for example, 86400 for 24 hours).

Store tokens securely. Never expose them in URLs, logs, or client-side source code.

Refreshing tokens

When your access token expires, use POST /auth/refresh-token with the refreshToken you received at sign-in to obtain a new access token without requiring the user to sign in again. See the login and session page for full details.

Multi-client support

Some endpoints that initiate user flows (such as sending a verification email) accept an optional clientAlias query parameter. This allows the platform to customise email branding and redirect URLs for different front-end clients deployed against the same API.

Use GET /auth/clientAliases to retrieve the list of valid aliases configured on your deployment.

curl http://localhost:5000/v1/auth/clientAliases

Authentication errors

Status	Meaning
401 Unauthorized	The request has no token, the token is malformed, or the token has expired.
403 Forbidden	The token is valid but the caller does not have the required role or organisation permission for the requested resource.

A 403 Forbidden response does not mean the token is invalid — it means the authenticated user lacks the necessary permissions. Requesting a new token will not resolve a permissions error.