# Get Token API

> Get the token of an API user or of a person from API Maker with the token API - username and password, or the name of a token generator, refresh tokens, several tokens in one call, and tenant tokens.

Source: https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-token-api.html

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](https://docs.apimaker.dev/v1/docs/getting-started/how-it-works.html#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`](https://docs.apimaker.dev/v1/examples/sys/system/getToken.html) |

## The token of an API user

**Body : without name, an API user of API Maker**

```json
{ "u": "default", "p": "12345", "expiresInSeconds": 259200 }
```

**Answer**

```json
{ "success": true, "statusCode": 200, "data": { "token": "eyJhbGciOi…", "refresh_token": "eyJhbGciOi…", "expires_in": 259200 } }
```

- `expiresInSeconds` is optional : `jwtOptions.expiresIn` of the [configuration](https://docs.apimaker.dev/v1/docs/am-resources/api-maker-configurations.html) 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**

```json
{ "name": "users_tg", "u": "alice@acme.com", "p": "PASSWORD" }
```

- The generator (an [auth provider](https://docs.apimaker.dev/v1/docs/authorization/AMDB.html) 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

```json
{ "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

```json
[
    { "u": "default", "p": "12345" },
    { "name": "users_tg", "u": "alice@acme.com", "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

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

{ "name": "users_tg", "u": "alice@acme.com", "p": "PASSWORD" }
```

- When the generator reads a users table of a [multi-tenant](https://docs.apimaker.dev/v1/docs/features/multi-tenant.html) 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](https://docs.apimaker.dev/v1/docs/settings/systemApiSettings.html) 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](https://docs.apimaker.dev/v1/docs/settings/systemApiSettings.html) give it `apiAccessType: TOKEN_ACCESS` (the token of an API user whose [group](https://docs.apimaker.dev/v1/docs/apis-security/api-group-permission.html) 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](https://docs.apimaker.dev/v1/docs/apis-all/hooks/preHook-api.html) run around it like around any API.
- The [request headers](https://docs.apimaker.dev/v1/docs/apis-all/header/requestHeader.html) 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. |

## Related

- [All APIs at a glance](https://docs.apimaker.dev/v1/docs/apis-all/overview.html) · [Response format](https://docs.apimaker.dev/v1/docs/apis-all/response-format.html) · [System API settings](https://docs.apimaker.dev/v1/docs/settings/systemApiSettings.html) · [System APIs from code](https://docs.apimaker.dev/v1/examples/sys/system/system.html)