---
pageClass: page-reference
---
# Authentication
> By default, all data in the system is off limits for unauthenticated users. To gain access to protected data, you must
> include an access token with every request, or
> [configure permissions for the public role](/guides/roles-and-permissions).
[[toc]]
---
## Login
Retrieve a temporary access token and refresh token.
### Request Body
`email` **Required**\
Email address of the user you're retrieving the access token for.
`password` **Required**\
Password of the user.
`otp`\
The user's one-time-password (if MFA is enabled).
`mode`\
Whether to retrieve the refresh token in the JSON response, or in a `httpOnly` `secure` cookie. One of `json`, `cookie`.
### Response Attributes
`access_token` **string**\
Temporary access token to be used in follow-up requests.
`expires` **integer**\
How long before the access token will expire. Value is in milliseconds.
`refresh_token` **string**\
The token that can be used to retrieve a new access token through [`/auth/refresh`](#refresh). Note: if you used `cookie`
as the mode in the request, the refresh token won't be returned in the JSON.
::: tip Expiry time
The token's expiration time can be configured through
[the `ACCESS_TOKEN_TTL` environment variable](/reference/environment-variables).
:::
### REST API
```
POST /auth/login
```
```json
{
"email": "admin@example.com",
"password": "d1r3ct5us"
}
```
### GraphQL
```graphql
mutation {
auth_login(email: "admin@example.com", password: "d1r3ctu5") {
access_token
refresh_token
}
}
```
---
## Refresh
Retrieve a new access token using a refresh token.
### Request Body
`refresh_token`\
The refresh token to use. If you have the refresh token in a cookie through [`/auth/login`](#login), you don't have to submit
it here.
### Response Attributes
`access_token` **string**\
Temporary access token to be used in follow-up requests.
`expires` **integer**\
How long before the access token will expire. Value is in milliseconds.
`refresh_token` **string**\
The token that can be used to retrieve a new access token through [`/auth/refresh`](#refresh). Note: if you used `cookie`
as the mode in the request, the refresh token won't be returned in the JSON.
### REST API
```
POST /auth/refresh
```
```json
{
"refresh_token": "gmPd...8wuB"
}
```
### GraphQL
```graphql
mutation {
auth_refresh(refresh_token: "abc...def") {
access_token
refresh_token
}
}
```
---
## Logout
Invalidate the refresh token thus destroying the user's session.
### Request Body
`refresh_token`\
The refresh token to invalidate. If you have the refresh token in a cookie through [`/auth/login`](#login), you don't have
to submit it here.
### REST API
```
POST /auth/logout
```
```json
{
"refresh_token": "gmPd...8wuB"
}
```
### GraphQL
```graphql
mutation {
auth_logout(refresh_token: "gmPd...8wuB")
}
```
---
## Request Password Reset
Request a password reset email to be sent to the given user.
### Request Body
`email` **Required**\
Email address of the user you're requesting a password reset for.
`reset_url`\
Provide a custom reset url which the link in the email will lead to. The reset token will be passed as a parameter.\
**Note**: You need to configure the
[`PASSWORD_RESET_URL_ALLOW_LIST` environment variable](/reference/environment-variables/#security) to enable this
feature.
### REST API
```
POST /auth/password/request
```
```json
{
"email": "admin@example.com"
}
```
### GraphQL
```graphql
mutation {
auth_password_request(email: "admin@example.com")
}
```
---
## Reset a Password
The request a password reset endpoint sends an email with a link to the admin app (or a custom route) which in turn uses
this endpoint to allow the user to reset their password.
### Request Body
`token` **Required**\
Password reset token, as provided in the email sent by the request endpoint.
`password` **Required**\
New password for the user.
### REST API
```
POST /auth/password/reset
```
```json
{
"token": "eyJh...KmUk",
"password": "d1r3ctu5"
}
```
### GraphQL
```graphql
mutation {
auth_password_reset(token: "eyJh...KmUk", password: "d1r3ctu5")
}
```
---
## List oAuth providers
List all the configured oAuth providers.
::: tip Configuring oAuth
To learn more about setting up oAuth providers, see
[Configuring SSO through oAuth](/guides/api-config/#oauth-single-sign-on-openid).
:::
### Response Attributes
`data` **Array**\
Array of configured oAuth providers.
```
GET /auth/oauth
```
```json
{
"data": ["GitHub", "Google", "Okta"]
}
```
---
## Login using oAuth provider
Will redirect to the configured oAuth provider for the user to login.
```
GET /auth/oauth/:provider
```
---