V.1.x.x

Authentication

Estimated reading: 3 minutes 228 views

Overview

The Authenticate API is used to generate an access token for calling protected OneDB API endpoints.

The generated token must be included in the request header when accessing APIs that require authentication.

Endpoint

https://<onedb-hostname>:8443/api/authenticate

Request Body

{
  "username": "api",
  "password": "api"
}

Request Fields

Field	Type	Required	Description
`username`	String	Yes	Username used to authenticate with OneDB API.
`password`	String	Yes	Password used to authenticate with OneDB API.

Successful Response

{
  "id": 10,
  "message": "Token has been generated!",
  "success": true,
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhcGkiLCJleHAiOjE3NzcxODAxMDcsImlhdCI6MTc3NzE2MjEwN30.JG2WROWg0jVVaiN-D_EMaL8ue9yX2tGOM5JCBuIxKmRWS9Fum5bqG0h10VkAQtNJ-BAsaWHQDe-0CyWpm7jBxQ"
}

Field	Type	Description
`id`	Number	Response identifier returned by OneDB.
`message`	String	Human-readable response message.
`success`	Boolean	Indicates whether the request was successful.
`token`	String	Generated access token used to call protected OneDB API endpoints.

Failed Response

{
  "id": 11,
  "message": "Invalid username or password",
  "success": false
}

Field	Type	Description
`id`	Number	Response identifier returned by OneDB.
`message`	String	Error message explaining why authentication failed.
`success`	Boolean	Indicates whether the request was successful. The value is `false` when authentication fails.

Token Usage

After authentication is successful, use the generated token as a Bearer token in the Authorization header when calling protected OneDB API endpoints.

Authorization: Bearer <token>

Example:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

Token Storage Note

The generated token should be stored persistently by the client application, either in a database, secure file, or secure credential storage mechanism.

For security reasons, avoid storing the token in plain text when possible.

Recommended storage options include:

Storage Option	Description
Database	Suitable when the application needs to reuse the token across services or sessions.
Secure File	Suitable for service-based integration where the token is used by a backend process.
Secret Manager	Recommended for production environments when available.

Token Expiration

OneDB uses a time-based JWT expiration mechanism. By default, the access token is valid for 5 hours from the time it is generated.

The token expiration is based on the token creation time, not user activity. This means the token will expire after 5 hours even if the user is still actively sending API requests.

Token generated at : 10:00 AM
Token validity     : 5 hours
Token expires at   : 03:00 PM

After the token expires, the user or application must authenticate again to obtain a new token.

Note: Token expiration is not the same as idle timeout. The token does not automatically extend its lifetime when API activity occurs.

Example Request Using cURL

curl -X POST "https://<onedb-hostname>:8443/api/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "api",
    "password": "api"
  }'

Notes

This API must be called before accessing protected OneDB API endpoints.
The token should be included in the Authorization header as a Bearer token.
The token should be stored securely and reused until it expires or becomes invalid.
If authentication fails, verify that the username and password are correct.
Do not expose API credentials or generated tokens in frontend code, logs, or public repositories.

Everything You Need to Know