Skip to main content

Authen

API Reference
POST/api/v1/auth/token

authentication with Encryption Algorithm AES-256-GCM

Authentication

Authentication endpoint. Credentials are encrypted using AES-256-GCM as described below.

Document History

versionpublish dateDescription
1.0.025-10-2026Intial Specification

The authentication process follows these steps​

  1. Prepare Credentials: Create a JSON object with your login credentials.

Credentials JSON Format​

accountCode
required
string
Account identifier code (generate by Gother)
Example: your-account-code
apiKey
required
string
API key (generate by Gother)
Example: your-api-key
clearPreviousSession
optional
boolean
Clear previous session. default false

Example Credentials JSON Format​

{
"accountCode": "your-account-code",
"apiKey": "your-api-key",
"clearPreviousSession": false
}
  1. Encrypt: Encrypt the JSON using AES-256-GCM with your secret key.

AES-256-GCM( nonce, key, plaintext(Credentials JSON) ) => ciphertext | tag

  • Nonce: 12-byte random value (unique for each encryption).
  • Key: Secret Key: A Base64-encoded 256-bit (32-byte) AES key, generated by Gother.
  • Plaintext: From step 1.
  1. Send Request: Send the encrypted payload to the API endpoint with your account code in the header.

encryptedPayload Structure​

encryptedPayload = Base64( Nonce[12 bytes] + Tag[16 bytes] + Ciphertext[variable] )

Components​

  1. Nonce: 12-byte random value (unique for each encryption) used in AES-256-GCM.
  2. Tag: 16-byte authentication tag that ensures data integrity.
  3. Ciphertext: Encrypted credentials JSON.

Header Parameters​

Content-Type
required
string
Content type
Example: application/json
x-account-code
required
string
Account identifier code; generate by Gother

Request Body​

encryptedPayload
required
string
Base64-encoded encrypted credentials
Example: Base64(Nonce + Tag + Ciphertext)

Response Schema​

ref
required
string
Reference transaction
status
required
boolean
Status flag
code
required
string
Error code
Example: 200 / 400...
message
required
string
Error message
data
required
object
Data response object
accessToken
required
string
The authentication token
Example: Bearer token
expiresIn
required
number
Token's expiration (in seconds)
tokenType
required
string
Token type
Example: Bearer

Responses​

Status CodeDescription
200SUCCESS
400Bad Request
401Unauthorized
404Not found
500Internal server error