> For the complete documentation index, see [llms.txt](https://docs.zetrix.com/mbi-vc-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zetrix.com/mbi-vc-api/api-specification/authentication.md).

# Authentication

## JWT Bearer Token Authentication

All endpoints (except public token endpoint) require a JWT Bearer Token:

Authorization: Bearer `eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...`

**Standard Authentication Flow:**

1. Obtain client credentials (`clientId` and `clientSecret`) from the system administrator
2. Call `/token/create` endpoint to get access and refresh tokens
3. Use the access token in the Authorization header for all subsequent API calls
4. When access token expires, use `/token/refresh` with the refresh token to get new tokens

**Tokens include scope-based access control:** 

* Normal tokens: scope `["vc", "vp"]` → access `/v1/vc/*` and `/v1/vp/*` endpoints
* Message signing tokens: scope \[`"vc:ext", "vp:ext"`] → access `/v1/vc/ext/*` and `/v1/vp/ext/*` endpoints

## Nonce-Based Message Signing Authentication

Secure token-based authentication flow for external consumers:

Authentication Flow:

1. Call `/v1/token/nonce?address=<address>` to get a unique nonce
2. Sign the nonce (not your address) using your private key
3. Call `/v1/token/create-with-signing` with signed nonce to get JWT token
4. Use the JWT token in the Authorization header for subsequent API calls

**Security Benefits:**

* Eliminates the security vulnerability of signing your own address
* Prevents replay attacks through nonce usage
* Provides consistent JWT-based authentication across all endpoints
* Scope-based access control for external operations

## Signing Authentication&#x20;

Specific external endpoints require message signing authentication using cryptographic signatures. The signed data represents the signature of the user's blockchain address.

<figure><img src="/files/xzt7IUowvrM6yUqitgEH" alt=""><figcaption></figcaption></figure>

#### Header

| Header        | Type   | Description                     |
| ------------- | ------ | ------------------------------- |
| Authorization | String | Bearer token for authentication |
| Content-Type  | String | Always `application/json`       |
| Accept        | String | Always `application/json`       |

**Message Signing Headers**

| Header         | Type   | Description                                            |
| -------------- | ------ | ------------------------------------------------------ |
| `signedData`   | String | Hex-encoded signature of the user's blockchain address |
| `publicKey`    | String | Public key for signature verification                  |
| `Content-Type` | String | Always `application/json`                              |
| `Accept`       | String | Always `application/json`                              |