Appearance
The Authentication
All data within the platform is private by default. The public role can be configured to expose data without authentication, or you can pass an access token to the API to access private data.
The Access Tokens
There are three types of tokens that can be used to authenticate within the Cloud Studio app 📟.
- Temporary Token (JWT) are returned by the login endpoint/mutation. These tokens have a relatively short expiration time, and are thus the most secure option to use. The tokens are returned with a refresh token that can be used to retrieve a new access token via the refresh endpoint/mutation.
- Session Token (JWT) can also be returned by the login endpoint/mutation. Session tokens combine both a refresh token and access token in a single cookie. These tokens should not have a short expiration time like the Temporary Tokens as you cannot refresh these after they have expired.
- Static Tokens can be set for each platform user, and never expire. They are less secure, but quite useful for server-to-server communication. Static Tokens are created in user settings inside of the the Cloud Studio app 📟 Data Studio User Module, or by updating the user's
token
value via API.
Once you have your access token, there are three ways to pass it to the API: in the request's Authorization
Header, as session cookie or via the access_token
query parameter.
The Authorization Header
Authorization: Bearer <token>
The Query Parameter
?access_token=<token>
WARNING
The query parameter option is not recommended in production setups as the parameter can get logged by various systems.
Login
Retrieve a temporary access token and refresh token.
The Request
json
// POST /auth/login
// POST /auth/login/:provider
{
"email": user_email,
"password": user_password
}
graphql
# POST /graphql/system
mutation {
auth_login(email: "user_email", password: "user_password") {
access_token
refresh_token
}
}
The 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 ahttpOnly
cookie. One ofjson
,cookie
orsession
. Defaults tojson
.
Response
access_token
string — Temporary access token to be used in follow-up requests. Note: if you usedsession
as the mode in the request, the access token won't be returned in the JSON.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
. Note: if you usedcookie
orsession
as the mode in the request, the refresh token won't be returned in the JSON.
Admin Login Example
For this example, we'll attempt to login for our admin user.
json
// POST /auth/login
// POST /auth/login/:provider
{
"email": "admin@example.com",
"password": "5ecur4-Pwd"
}
graphql
# POST /graphql/system
mutation {
auth_login(email: "admin@example.com", password: "5ecur4-Pwd") {
access_token
refresh_token
}
}
Refresh
Retrieve a new access token using a refresh token.
Request
json
// POST /auth/refresh
{
"refresh_token": refresh_token_string,
"mode": refresh_mode
}
graphql
# POST /graphql/system
mutation {
auth_refresh(refresh_token: "refresh_token", mode: refresh_mode) {
access_token
refresh_token
}
}
The Request Body
refresh_token
— The refresh token to use. If you have the refresh token in a cookie through/auth/login
, you don't have to submit it here.mode
— Whether to submit and retrieve the refresh token in the JSON response, or in ahttpOnly
cookie. One ofjson
,cookie
orsession
.
Response
access_token
string — Temporary access token to be used in follow-up requests. Note: if you usedsession
as the mode in the request, the access token won't be returned in the JSON.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
. Note: if you usedcookie
orsession
as the mode in the request, the refresh token won't be returned in the JSON.
Refresh Token Access Example
For this example, we'll attempt to gain access through a refresh token.
json
// POST /auth/refresh
{
"refresh_token": "gmPd...8wuB",
"mode": "json"
}
graphql
# POST /graphql/system
mutation {
auth_refresh(refresh_token: "abc...def", mode: json) {
access_token
refresh_token
}
}
Logout
Invalidate the refresh token thus destroying the user's session.
Request
json
// POST /auth/logout
{
"refresh_token": refresh_token
}
graphql
# POST /graphql/system
mutation {
auth_logout(refresh_token: "refresh_token")
}
The Request Body
refresh_token
— The refresh token to invalidate. If you have the refresh token in a cookie through/auth/login
, you don't have to submit it here.mode
— Whether the refresh token is submitted in the JSON response, or in ahttpOnly
cookie. One ofjson
,cookie
orsession
.
Destroy Refresh Token Example
For this example, we'll attempt to log out which will destroy the provided refresh token.
json
// POST /auth/logout
{
"refresh_token": "gmPd...8wuB",
"mode": "json"
}
graphql
# POST /graphql/system
mutation {
auth_logout(refresh_token: "gmPd...8wuB", mode: "json")
}
Request Password Reset
Request a password reset email to be sent to the given user.
The Request
json
// POST /auth/password/request
{
"email": user_email
}
graphql
# POST /graphql/system
mutation {
auth_password_request(email: "user_email")
}
The 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.
Request Password Reset Example
For this example, we'll request a new password by providing an email address.
json
// POST /auth/password/request
{
"email": "admin@example.com"
}
graphql
# POST /graphql/system
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.
The Request
json
// POST /auth/password/reset
{
"token": password_reset_token,
"password": password
}
graphql
# POST /graphql/system
mutation {
auth_password_reset(token: "password_reset_token", password: "password")
}
The Request Body
token
Required — Password reset token, as provided in the email sent by the request endpoint.password
Required — New password for the user.
Reset Password Example
For this example, we'll attempt to reset the password by using the reset token provided over email.
json
// POST /auth/password/reset
{
"token": "eyJh...KmUk",
"password": "d1r3ctu5"
}
graphql
# POST /graphql/system
mutation {
auth_password_reset(token: "eyJh...KmUk", password: "d1r3ctu5")
}
List Auth Providers
List all the configured auth providers.
Request
http
GET /auth
Response
json
{
"data": [
{
"name": "GitHub",
"driver": "oauth2",
"icon": "github"
},
{
"name": "Google",
"driver": "openid",
"icon": "google"
},
{
"name": "Okta",
"driver": "openid"
}
],
"disableDefault": false
}
data
Array — Array of configured auth providers.disableDefault
boolean — Whether or not the default authentication provider is disabled.
Login Using SSO Providers
Will redirect to the configured SSO provider for the user to login.
Request
http
GET /auth/login/:provider