# Request an access token

Exchanges a set of client credentials and a user's sign-in details for an access token.
Every other endpoint in this API expects the result in an
`Authorization: Bearer <access_token>` header, so this is the first call an integration
makes.
You need a `client_id` and `client_secret` before you can call it. The client id is the
`id` of one of your personal access clients - see the listing endpoint below. Rosterfy
issues the matching secret; no endpoint returns it.
The token is issued for the user whose `username` and `password` you send, and it carries
exactly that user's access. Use a dedicated integration user rather than a person's own
login, so the integration keeps working when people come and go and so its activity is
distinguishable in the audit trail.
`expires_in` is the lifetime in seconds - 2592000, or 30 days. The `refresh_token` returned
alongside it lasts longer than the access token and can be exchanged for a new one by
calling this endpoint again with `grant_type` set to `refresh_token`, sending
`refresh_token` in place of `username` and `password`. Refresh before the access token
expires rather than after; once it has lapsed there is nothing to refresh and you are back
to a full credential exchange.
The body may be sent as JSON or as `application/x-www-form-urlencoded`. Both are accepted
and both return JSON.
Treat the access token as a credential in its own right. It is a bearer token: anything
holding it has the user's access for as long as it lives, so store it the way you would
store the password you exchanged for it, and never put it in a URL or a log.

Endpoint: POST /api/v2/oauth/token
Version: 2.0.0
Security: default

## Request fields (application/json):

  - `grant_type` (string, required)
    The exchange being performed. Send `password` for the initial exchange, or `refresh_token` to renew an existing token.
    Enum: "password", "refresh_token"

  - `client_id` (integer, required)
    The id of the personal access client the credentials belong to.

  - `client_secret` (string, required)
    The secret issued with that client.

  - `username` (string)
    The email address of the user the token is issued for. Required when `grant_type` is `password`.

  - `password` (string)
    That user's password. Required when `grant_type` is `password`.

  - `refresh_token` (string)
    The refresh token from an earlier exchange. Required when `grant_type` is `refresh_token`, and ignored otherwise.

  - `scope` (string)
    Optional. Omit it, or send `*`, to receive a token carrying the whole of the user's access.

## Response 200 fields (application/json):

  - `token_type` (string)
    Always `Bearer`. This is the scheme to use in the Authorization header.

  - `expires_in` (integer)
    Seconds until the access token expires.

  - `access_token` (string)
    The token to send as `Authorization: Bearer <access_token>`.

  - `refresh_token` (string)
    Exchange this for a new access token before the current one expires.