BrigitAPI Authentication Guide

Introduction

BrigitAPI supports two authentication methods to ensure secure access to its endpoints: Basic Authentication and JWT (JSON Web Token) Authentication. Both methods require consumers to provide valid credentials to access the API.

  • Basic Authentication is the default method for standard users.
  • JWT Authentication is an advanced option, providing additional capabilities such as tenant impersonation for specific authorized users.

Basic Authentication

What is Basic Authentication?

Basic Authentication is a simple authentication scheme built into the HTTP protocol. It works by sending a base64 encoded string containing the username and password in the Authorization header of the HTTP request.

How to Encode Credentials

  1. Combine your username and password:

    • Format: username:password

  2. Encode the combined string:

    • Use base64 encoding to encode the string.

Example

If your username is user1 and your password is password123, the combined string will be:

user1:password123

When base64 encoded, this becomes:

dXNlcjE6cGFzc3dvcmQxMjM=

HTTP Request

You need to include the encoded credentials in the Authorization header of your HTTP request. The header format is:

Authorization: Basic <base64_encoded_credentials>

For the example above, the header would be:

Authorization: Basic dXNlcjE6cGFzc3dvcmQxMjM=

Sample Request

Here is a sample HTTP request using cURL:

curl -X GET "https://api-v1.brigit.online/endpoint" -H "Authorization: Basic dXNlcjE6cGFzc3dvcmQxMjM="

Using Postman

  1. Open Postman and create a new request.
  2. Select the Authorization tab.
  3. Choose Basic Auth from the dropdown menu.
  4. Enter your username and password.
  5. Postman will automatically encode these credentials and include them in the Authorization header.

Common Errors for Basic Authentication

  1. 401 Unauthorized:

    • Occurs when the username or password is missing, incorrect, or improperly encoded. Ensure that your credentials are correct and encoded in base64 format before including them in the request header.

  2. 403 Forbidden:

    • This error occurs when your credentials are valid, but you do not have permission to access the resource. Check with your administrator to ensure you have the correct access permissions.

  3. 400 Bad Request:

    • This occurs if the request format is incorrect or the credentials are missing in the Authorization header. Verify that your request format is correct and the header includes valid credentials.

  4. 500 Internal Server Error:

    • This error typically indicates an issue on the server. Review your request or try again later. If the issue persists, contact support for further assistance.

JWT Authentication (Advanced)

What is JWT Authentication?

JWT (JSON Web Token) Authentication allows users to securely access API resources by exchanging tokens. It provides advanced users additional capabilities, such as tenant impersonation, enabling them to act on behalf of another tenant. This advanced feature is available only to users with special permissions.

Key Features of JWT Authentication

  • Tokens: JWT tokens are obtained via the BrigitAPI authentication endpoint.
  • Impersonation: Authorized advanced users can request to impersonate another tenant by including a tenant_id in the request. This feature is restricted to specific advanced users.
  • Security: JWTs are signed and verified to ensure the integrity of the requestor.

Endpoint for Obtaining a JWT Token

To obtain a JWT token, send a POST request to the /api/authentication/get-token endpoint with your username and password.

Request Format:

  • Endpoint: /authentication/get-token
  • Method: POST
  • Request Body:
    • username: Your username
    • password: Your password
    • tenant_id (optional): If you need to impersonate another tenant (for advanced users only)

Sample Request:

curl -X POST "https://api-v1.brigit.online/authentication/get-token" \
-H "Content-Type: application/json" \
-d '{
  "username": "admin",
  "password": "adminpassword"
}'

Sample Request with Tenant Impersonation:

If you have the required permissions and wish to impersonate another tenant, you can include the tenant_id in your request:

curl -X POST "https://api-v1.brigit.online/authentication/get-token" \
-H "Content-Type: application/json" \
-d '{
  "username": "admin",
  "password": "adminpassword",
  "tenant_id": "12345"
}'

Using the JWT Token

Once you receive the JWT token from the /api/authentication/get-token endpoint, you need to include it in the Authorization header of subsequent requests.

Example Authorization Header Format:

Authorization: Bearer <your_jwt_token>

Sample Request with JWT Token:

curl -X GET "https://api-v1.brigit.online/endpoint" \
-H "Authorization: Bearer <your_jwt_token>"

Using JWT in Postman

  1. Open Postman and create a new request.
  2. Select the Authorization tab.
  3. Choose Bearer Token from the dropdown menu.
  4. Enter the JWT token you received from the /api/authentication/get-token endpoint.
  5. The token will be included in the Authorization header for all requests.

Common Errors for JWT Authentication

  1. 401 Unauthorized:

    • Occurs when the JWT token is missing, expired, or invalid. Ensure that the token is properly included in the Authorization header and hasn�t expired.

  2. 403 Forbidden:

    • This error indicates that while your token is valid, you do not have sufficient permissions to access the resource. Impersonation of a tenant requires advanced permissions.

  3. 400 Bad Request:

    • This error occurs if the request payload for token generation is invalid, such as missing username or password, or if the tenant_id is incorrectly formatted.

  4. 500 Internal Server Error:

    • This error occurs if there is an issue on the server while processing the request. Please review the request payload or retry later.