Skip to content
/Authentication

Request an access token

Request

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.

Bodyapplication/jsonrequired
grant_typestringrequired

The exchange being performed. Send password for the initial exchange, or refresh_token to renew an existing token.

Enum:"password""refresh_token"
client_idintegerrequired

The id of the personal access client the credentials belong to.

client_secretstringrequired

The secret issued with that client.

usernamestring

The email address of the user the token is issued for. Required when grant_type is password.

passwordstring

That user's password. Required when grant_type is password.

refresh_tokenstring

The refresh token from an earlier exchange. Required when grant_type is refresh_token, and ignored otherwise.

scopestring

Optional. Omit it, or send *, to receive a token carrying the whole of the user's access.

curl -i -X POST \
  https://developer.rosterfy.com/_mock/api-docs/openapi/api/v2/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "password",
    "client_id": 1234,
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "username": "integration@example.com",
    "password": "{YOUR_PASSWORD}",
    "scope": "*"
  }'

Responses

A new access token.

Bodyapplication/json
token_typestring

Always Bearer. This is the scheme to use in the Authorization header.

expires_ininteger

Seconds until the access token expires.

access_tokenstring

The token to send as Authorization: Bearer <access_token>.

refresh_tokenstring

Exchange this for a new access token before the current one expires.

Response
{
  "token_type": "Bearer",
  "expires_in": 2592000,
  "access_token": "{ACCESS_TOKEN}",
  "refresh_token": "{REFRESH_TOKEN}"
}