# Authentication API

## Authentication API

This API provides access tokens used to authenticate all other API requests.\
Clients must obtain a token and include it as a **Bearer token** in the `Authorization` header.

***

### Token Endpoint

**POST** `/api/v1/authentication/token`

Issues a JSON Web Token (JWT) and refresh token based on the provided credentials and request context.

#### Request

**Headers**

| Header       | Value            | Required |
| ------------ | ---------------- | -------- |
| Content-Type | application/json | Yes      |

**Body**

```json
{
  "username": "string",
  "password": "string",
  "scopes": "string",
  "code": "string",
  "businessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "onBehalfOfUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

**Request Field Descriptions**

| Field              | Type   | Required | Description                                                              |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------ |
| `username`         | string | Yes      | Username or login identifier used for authentication                     |
| `password`         | string | Yes      | Password associated with the provided username                           |
| `scopes`           | string | No       | Space- or comma-delimited list of requested authorization scopes         |
| `code`             | string | No       | Optional authorization or verification code (for MFA or delegated flows) |
| `businessUnitId`   | GUID   | No       | Identifies the business unit context for which the token is requested    |
| `onBehalfOfUserId` | GUID   | No       | User ID that the token is acting on behalf of (delegated access)         |
| `productId`        | GUID   | No       | Product context associated with the token                                |

#### Response

**Body**

```json
{
  "jwt": "string",
  "refreshToken": "string",
  "expiresInSeconds": 0,
  "activeBusinessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "onBehalfOfUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "scopes": "string"
}
```

**Response Field Descriptions**

| Field                  | Type   | Description                                                   |
| ---------------------- | ------ | ------------------------------------------------------------- |
| `jwt`                  | string | JSON Web Token used to authenticate API requests              |
| `refreshToken`         | string | Token used to obtain a new JWT when the current token expires |
| `expiresInSeconds`     | number | Token lifetime in seconds                                     |
| `activeBusinessUnitId` | GUID   | Business unit context associated with the issued token        |
| `onBehalfOfUserId`     | GUID   | User ID the token is acting on behalf of, if applicable       |
| `productId`            | GUID   | Product context associated with the token                     |
| `scopes`               | string | Authorization scopes granted to the token                     |

#### Using the Access Token

Include the JWT in the `Authorization` header for all protected API calls:

Authorization: Bearer

#### Error Responses

| HTTP Status | Description                                |
| ----------- | ------------------------------------------ |
| 400         | Invalid request or missing required fields |
| 401         | Invalid username or password               |
| 403         | Insufficient permissions or scope          |
| 500         | Internal authentication service error      |

***

### Security Notes

* All requests must be sent over HTTPS
* Never expose JWTs or refresh tokens in URLs or logs
* Store refresh tokens securely
* Unless explicitly stated otherwise, all API endpoints require Bearer authentication


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.comcorp.co.za/askmefirst/authentication-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.