Sign-in and sessions

Auth Config

GET

/auth/config

Response Body

Successful Response

application/json

response

google_client_id*string|null

Example Request

curl -X GET 'https://example.com/auth/config'

Example Request

curl -X GET 'https://example.com/auth/config'

Example ResponseSchema200

{
  "google_client_id": "string"
}

{  "google_client_id": "string"}

Email Start

POST

/auth/email/start

Request Body

application/json

body

email*Email

purpose?Purpose

Default"continue"

Value in"continue""reset_password"

Response Body

Successful Response

application/json

response

resend_in_seconds*Resend In Seconds

expires_in_seconds*Expires In Seconds

Example Request

curl -X POST 'https://example.com/auth/email/start' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string"
}'

Example Request

curl -X POST 'https://example.com/auth/email/start' \  -H 'Content-Type: application/json' \  -d '{  "email": "string"}'

Example ResponseSchema

{
  "resend_in_seconds": 0,
  "expires_in_seconds": 0
}

{  "resend_in_seconds": 0,  "expires_in_seconds": 0}

Email Verify

POST

/auth/email/verify

Query Parameters

client?Client

native returns tokens in the body instead of setting cookies

Default"web"

Value in"web""native"

Request Body

application/json

body

email*Email

code*Code

Match^\d{6}$

Response Body

Successful Response

application/json

response

status*Status

Value in"signed_in""needs_profile"

user?|null

registration_token?string|null

tokens?|null

Example Request

curl -X POST 'https://example.com/auth/email/verify' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string",
  "code": "string"
}'

Example Request

curl -X POST 'https://example.com/auth/email/verify' \  -H 'Content-Type: application/json' \  -d '{  "email": "string",  "code": "string"}'

Example ResponseSchema

{
  "status": "signed_in",
  "user": {
    "id": "string",
    "email": "string",
    "display_name": "string",
    "avatar_url": "string",
    "locale": "string",
    "has_password": true,
    "identities": [
      {
        "provider": "google",
        "email": "string",
        "created_at": "2019-08-24T14:15:22Z"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z"
  },
  "registration_token": "string",
  "tokens": {
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 0
  }
}

{  "status": "signed_in",  "user": {    "id": "string",    "email": "string",    "display_name": "string",    "avatar_url": "string",    "locale": "string",    "has_password": true,    "identities": [      {        "provider": "google",        "email": "string",        "created_at": "2019-08-24T14:15:22Z"      }    ],    "created_at": "2019-08-24T14:15:22Z"  },  "registration_token": "string",  "tokens": {    "access_token": "string",    "refresh_token": "string",    "token_type": "Bearer",    "expires_in": 0  }}

Register Complete

POST

/auth/register/complete

Query Parameters

client?Client

native returns tokens in the body instead of setting cookies

Default"web"

Value in"web""native"

Request Body

application/json

body

registration_token*Registration Token

Lengthlength <= 200

display_name*Display Name

Length1 <= length <= 60

password?|null

Response Body

Successful Response

application/json

response

status*Status

Value in"signed_in""needs_profile"

user?|null

registration_token?string|null

tokens?|null

Example Request

curl -X POST 'https://example.com/auth/register/complete' \
  -H 'Content-Type: application/json' \
  -d '{
  "registration_token": "string",
  "display_name": "string"
}'

Example Request

curl -X POST 'https://example.com/auth/register/complete' \  -H 'Content-Type: application/json' \  -d '{  "registration_token": "string",  "display_name": "string"}'

Example ResponseSchema

{
  "status": "signed_in",
  "user": {
    "id": "string",
    "email": "string",
    "display_name": "string",
    "avatar_url": "string",
    "locale": "string",
    "has_password": true,
    "identities": [
      {
        "provider": "google",
        "email": "string",
        "created_at": "2019-08-24T14:15:22Z"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z"
  },
  "registration_token": "string",
  "tokens": {
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 0
  }
}

{  "status": "signed_in",  "user": {    "id": "string",    "email": "string",    "display_name": "string",    "avatar_url": "string",    "locale": "string",    "has_password": true,    "identities": [      {        "provider": "google",        "email": "string",        "created_at": "2019-08-24T14:15:22Z"      }    ],    "created_at": "2019-08-24T14:15:22Z"  },  "registration_token": "string",  "tokens": {    "access_token": "string",    "refresh_token": "string",    "token_type": "Bearer",    "expires_in": 0  }}

POST

/auth/password/login

Query Parameters

client?Client

native returns tokens in the body instead of setting cookies

Default"web"

Value in"web""native"

Request Body

application/json

body

email*Email

password*Password

Length1 <= length <= 256

Response Body

Successful Response

application/json

response

status*Status

Value in"signed_in""needs_profile"

user?|null

registration_token?string|null

tokens?|null

Example Request

curl -X POST 'https://example.com/auth/password/login' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string",
  "password": "string"
}'

Example Request

curl -X POST 'https://example.com/auth/password/login' \  -H 'Content-Type: application/json' \  -d '{  "email": "string",  "password": "string"}'

Example ResponseSchema

{
  "status": "signed_in",
  "user": {
    "id": "string",
    "email": "string",
    "display_name": "string",
    "avatar_url": "string",
    "locale": "string",
    "has_password": true,
    "identities": [
      {
        "provider": "google",
        "email": "string",
        "created_at": "2019-08-24T14:15:22Z"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z"
  },
  "registration_token": "string",
  "tokens": {
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 0
  }
}

{  "status": "signed_in",  "user": {    "id": "string",    "email": "string",    "display_name": "string",    "avatar_url": "string",    "locale": "string",    "has_password": true,    "identities": [      {        "provider": "google",        "email": "string",        "created_at": "2019-08-24T14:15:22Z"      }    ],    "created_at": "2019-08-24T14:15:22Z"  },  "registration_token": "string",  "tokens": {    "access_token": "string",    "refresh_token": "string",    "token_type": "Bearer",    "expires_in": 0  }}

Password Reset

POST

/auth/password/reset

Query Parameters

client?Client

native returns tokens in the body instead of setting cookies

Default"web"

Value in"web""native"

Request Body

application/json

body

email*Email

code*Code

Match^\d{6}$

new_password*New Password

Length1 <= length <= 256

Response Body

Successful Response

application/json

response

status*Status

Value in"signed_in""needs_profile"

user?|null

registration_token?string|null

tokens?|null

Example Request

curl -X POST 'https://example.com/auth/password/reset' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string",
  "code": "string",
  "new_password": "string"
}'

Example Request

curl -X POST 'https://example.com/auth/password/reset' \  -H 'Content-Type: application/json' \  -d '{  "email": "string",  "code": "string",  "new_password": "string"}'

Example ResponseSchema

{
  "status": "signed_in",
  "user": {
    "id": "string",
    "email": "string",
    "display_name": "string",
    "avatar_url": "string",
    "locale": "string",
    "has_password": true,
    "identities": [
      {
        "provider": "google",
        "email": "string",
        "created_at": "2019-08-24T14:15:22Z"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z"
  },
  "registration_token": "string",
  "tokens": {
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 0
  }
}

{  "status": "signed_in",  "user": {    "id": "string",    "email": "string",    "display_name": "string",    "avatar_url": "string",    "locale": "string",    "has_password": true,    "identities": [      {        "provider": "google",        "email": "string",        "created_at": "2019-08-24T14:15:22Z"      }    ],    "created_at": "2019-08-24T14:15:22Z"  },  "registration_token": "string",  "tokens": {    "access_token": "string",    "refresh_token": "string",    "token_type": "Bearer",    "expires_in": 0  }}

POST

/auth/google

Query Parameters

client?Client

native returns tokens in the body instead of setting cookies

Default"web"

Value in"web""native"

Request Body

application/json

body

id_token*Id Token

Lengthlength <= 4096

Response Body

Successful Response

application/json

response

status*Status

Value in"signed_in""needs_profile"

user?|null

registration_token?string|null

tokens?|null

Example Request

curl -X POST 'https://example.com/auth/google' \
  -H 'Content-Type: application/json' \
  -d '{
  "id_token": "string"
}'

Example Request

curl -X POST 'https://example.com/auth/google' \  -H 'Content-Type: application/json' \  -d '{  "id_token": "string"}'

Example ResponseSchema

{
  "status": "signed_in",
  "user": {
    "id": "string",
    "email": "string",
    "display_name": "string",
    "avatar_url": "string",
    "locale": "string",
    "has_password": true,
    "identities": [
      {
        "provider": "google",
        "email": "string",
        "created_at": "2019-08-24T14:15:22Z"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z"
  },
  "registration_token": "string",
  "tokens": {
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 0
  }
}

{  "status": "signed_in",  "user": {    "id": "string",    "email": "string",    "display_name": "string",    "avatar_url": "string",    "locale": "string",    "has_password": true,    "identities": [      {        "provider": "google",        "email": "string",        "created_at": "2019-08-24T14:15:22Z"      }    ],    "created_at": "2019-08-24T14:15:22Z"  },  "registration_token": "string",  "tokens": {    "access_token": "string",    "refresh_token": "string",    "token_type": "Bearer",    "expires_in": 0  }}

Token Refresh

POST

/auth/token/refresh

Request Body

application/json

body

refresh_token*Refresh Token

Lengthlength <= 200

Response Body

Successful Response

application/json

response

access_token*Access Token

refresh_token*Refresh Token

token_type?Token Type

Default"Bearer"

expires_in*Expires In

Access token lifetime in seconds

Example Request

curl -X POST 'https://example.com/auth/token/refresh' \
  -H 'Content-Type: application/json' \
  -d '{
  "refresh_token": "string"
}'

Example Request

curl -X POST 'https://example.com/auth/token/refresh' \  -H 'Content-Type: application/json' \  -d '{  "refresh_token": "string"}'

Example ResponseSchema

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 0
}

{  "access_token": "string",  "refresh_token": "string",  "token_type": "Bearer",  "expires_in": 0}

Logout

POST

/auth/logout

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Response Body

Successful Response

application/json

response

ok?Ok

Defaulttrue

Example Request

curl -X POST 'https://example.com/auth/logout'

Example Request

curl -X POST 'https://example.com/auth/logout'

Example ResponseSchema200

{
  "ok": true
}

{  "ok": true}

Auth ConfigCopy Anchor Link

Response BodyCopy Anchor Link

Email StartCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Email VerifyCopy Anchor Link

Query ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Register CompleteCopy Anchor Link

Query ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Password LoginCopy Anchor Link

Query ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Password ResetCopy Anchor Link

Query ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Google LoginCopy Anchor Link

Query ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Token RefreshCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

LogoutCopy Anchor Link

AuthorizationCopy Anchor Link

Response BodyCopy Anchor Link

Auth Config

Response Body

Email Start

Request Body

Response Body

Email Verify

Query Parameters

Request Body

Response Body

Register Complete

Query Parameters

Request Body

Response Body

Password Login

Query Parameters

Request Body

Response Body

Password Reset

Query Parameters

Request Body

Response Body

Google Login

Query Parameters

Request Body

Response Body

Token Refresh

Request Body

Response Body

Logout

Authorization

Response Body