Skip to content
This page View Markdown Open in ChatGPT Open in Claude

Get token

Gives the two tokens every call may need : the token of an API user (which application calls, sent in x-am-authorization) and the token of a person, a row of your own users table read by a DB token generator (sent in x-am-user-authorization). See the two gates.
Method POST
URL /api/system-api/admin/token : admin is the user path of your account
Body { u, p, expiresInSeconds? }, { name, u, p }, { refresh_token, name? }, or an array of them
Answer data : { token, refresh_token, expires_in }, or an array
From code g.sys.system.getToken

The token of an API user

Body : without name, an API user of API Maker
{ "u": "default", "p": "12345", "expiresInSeconds": 259200 }
Answer
{ "success": true, "statusCode": 200, "data": { "token": "eyJhbGciOi…", "refresh_token": "eyJhbGciOi…", "expires_in": 259200 } }
  • expiresInSeconds is optional : jwtOptions.expiresIn of the configuration otherwise (72 hours by default).
  • The password of an API user lives in the secret, under the path set on the API user (common.apiUserPasswords.default for the API user of a new account).

The token of a person

Body : with the name of a token generator
{ "name": "users_tg", "u": "[email protected]", "p": "PASSWORD" }
  • The generator (an auth provider of type DB) knows the users table and its username and password columns. A hashed password column works : the password given is hashed and compared.
  • The groups of the person come from the groups column of the generator.

Refresh

{ "name": "users_tg", "refresh_token": "eyJhbGciOi…" }
  • refresh_token of an earlier answer gives a new token without the password. For a person, add the name of the generator. A refresh token is valid refreshTokenValidForS seconds (900 by default) after the token expired.

Several tokens in one call

[
    { "u": "default", "p": "12345" },
    { "name": "users_tg", "u": "[email protected]", "p": "PASSWORD" }
]
  • The answer is an array in the same order. The sample custom API /default/login of a new account does exactly this and returns both tokens to the app.

The token of a tenant user

POST /api/system-api/admin/token
x-am-tenant-username: acme

{ "name": "users_tg", "u": "[email protected]", "p": "PASSWORD" }
  • When the generator reads a users table of a multi-tenant instance, name the tenant : the person is read from the database of that tenant, and the token works for that tenant only, also after a refresh.

Who may call it

  • The token API is public by default : anybody can ask for a token with a username and a password.
  • When its system API settings list auth providers, it needs the tokens those settings ask for, like any other API.
  • A token is a JWT signed with passJWT of the server. Changing the password of the API user, or passwordChangedAtColumn of a person, invalidates the tokens made before.

Access and settings

  • Over HTTP, a system API answers once its settings give it apiAccessType: TOKEN_ACCESS (the token of an API user whose group grants this system API, in x-am-authorization) or IS_PUBLIC. Without settings it is NO_ACCESS : your code calls it through g.sys, the admin panel tests it, and an HTTP call is refused. The token API itself is public unless its settings say otherwise.
  • The settings can also cache the answer or require person tokens (authProviders) ; pre and post hooks run around it like around any API.
  • The request headers apply : x-am-response-case, x-am-content-type-response, x-am-internationalization, x-am-tenant-username…

Errors

Code When
400 The body is wrong : the message names the missing or invalid key, Please provide token request with ['u', 'p'] or ['refresh_token']. for an incomplete body.
401 No valid API user token, or the API is NO_ACCESS : You are not authorized to access this API.
403 No group grants this system API.