Token Endpoint & Refresh

The token endpoint is at https://hub.spookysrv.com/index.php?route=/api/v2/oauth2/token

We only accept a POST request at the Token Endpoint

Content Type must be application/x-www-form-urlencode

Each callback code is can be used ONCE only

Request (Format 1)

Include client_id, client_secret, and code in the POST data field / POST request body

For refreshing an access token, pass refresh_token and grant_type=refresh_token in the POST data field / POST request body.

Example CURL Request:

curl -X POST "https://hub.spookysrv.com/index.php?route=/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=5ScKa4HaYEFo8uWEKo7O0Vb9nSjxZzigKsTdliBP06M&client_secret=EUx6bSBAm48vgtbHv6hYWTk3UOWSFIyPZDB6aGXSY&code=BREmfapICBknG5daa8h5H60DoUOWDXAlm6HY3fCvE4" 

Example CURL Request: (Refresh Token)

curl -X POST "https://hub.spookysrv.com/index.php?route=/api/v2/oauth2/token"
-H "Content-Type: application/x-www-form-urlencoded"
-d "client_id=5ScKa4HaYEFo8uWEKo7O0Vb9nSjxZzigKsTdliBP06M&client_secret=EUx6bSBAm48vgtbHv6hYWTk3UOWSFIyPZDB6aGXSY&refresh_token=ZEPrdekJ8fo54BuRyIViZNrG8CQtjyLjNW0pfwDXZ4&grant_type=refresh_token"

grant_type=refresh_token must be passed when using a refresh token

Request (Format 2)

Include code in the POST data field / POST request body Include client_id and client_secret in the Authorization header

Authorization header must be of Basic authentication type, and authentication credentials will be a base64-encoded string of format client_id:client_secret

Example: Authorization: Basic NVNjS2E0SGFZRUZvOHVXRUtvN08wVmI5blNqeFp6aWdLc1RkbGlCUDA2TTpFVXg2YlNCQW00OHZndGJIdjZoWVdUazNVT1dTRkl5UFpEQjZhR1hTWQ==

For refreshing an access token, pass refresh_token and grant_type=refresh_token in the POST data field / POST request body.

Example CURL Request:

curl -X POST "https://hub.spookysrv.com/index.php?route=/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic NVNjS2E0SGFZRUZvOHVXRUtvN08wVmI5blNqeFp6aWdLc1RkbGlCUDA2TTpFVXg2YlNCQW00OHZndGJIdjZoWVdUazNVT1dTRkl5UFpEQjZhR1hTWQ==" \
  -d "code=BREmfapICBknG5daa8h5H60DoUOWDXAlm6HY3fCvE4"

Example CURL Request: (Refresh Token)

curl -X POST "https://hub.spookysrv.com/index.php?route=/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic NVNjS2E0SGFZRUZvOHVXRUtvN08wVmI5blNqeFp6aWdLc1RkbGlCUDA2TTpFVXg2YlNCQW00OHZndGJIdjZoWVdUazNVT1dTRkl5UFpEQjZhR1hTWQ==" \
  -d "refresh_token=ZEPrdekJ8fo54BuRyIViZNrG8CQtjyLjNW0pfwDXZ4&grant_type=refresh_token"

grant_type=refresh_token must be passed when using a refresh token

Response

A JSON response will be returned in the following format:

{
    "access_token":"5zW2vSctAvjKUE7uRy7gJ6GNdS66Hkeex7TByUoJsM",
    "refresh_token":"0zJtoF01Com08bwR8byryUuo1NRFmtO4kMju1QnWBE",
    "token_type": "Bearer"
}

If requested with a refresh token, both tokens are regenerated. Please save the new refresh token.

Response (OIDC)

A JSON response will be returned in the following format:

{
  "access_token": "5zW2vSctAvjKUE7uRy7gJ6GNdS66Hkeex7TByUoJsM",
  "refresh_token": "0zJtoF01Com08bwR8byryUuo1NRFmtO4kMju1QnWBE",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6Ijk2ZDFkNDQ3ZWVhMGEyMDhmZDMzNzZmNTBmZWFlNjQxIn0.eyJpc3MiOiJodHRwczovL2F1dGguc3Bvb2t5c3J2LmNvbS9vaWRjLyIsImF1ZCI6IjVTY0thNEhhWUVGbzh1V0VLbzdPMFZiOW5TanhaemlnS3NUZGxpQlAwNk0iLCJqdGkiOiIxIiwiaWF0IjoxNzUyMjAyODQwLjAzMzgxNiwiZXhwIjoxNzUyMjA2NTAwLjAzMzgxNiwiaWQiOjEsIm5hbWUiOiJTcG9va3lLaXBwZXIiLCJlbWFpbCI6Im9hdXRoMjpzcG9va3lzcnZfbm9fZW1haWxfc2NvcGUiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZX0.YMwCaz8PLPQA4fkAev5nZIwSo3PkuF6DgKlze3KaDK0QkaIpRgCrFw4XrBPJKq62bFWp4ie7r4oc3Mo6HkFFdg",
  "token_type": "Bearer",
  "expires_in": 3540,
  "scope": "openid identify"
}

If requested with a refresh token, both access_token and refresh_token are regenerated. Please save the new refresh token.

id_token is in JSON Web Token (JWT) format

The decoded header of the JWT in JSON should be as follows:

{
  "typ": "JWT",
  "alg": "ES256",
  "kid": "96d1d447eea0a208fd3376f50feae641"
}

The decoded payload of the JWT in JSON should be as follows:

{
  "iss": "https://auth.spookysrv.com/oidc/", // static
  "aud": "5ScKa4HaYEFo8uWEKo7O0Vb9nSjxZzigKsTdliBP06M", // client id
  "jti": "1", 
  "iat": 1752202840.033816,
  "exp": 1752206500.033816,
  "id": 1,
  "sub": 1, // same as `id`
  "name": "Username",
  "email": "[email protected]", // will be `oauth2:spookysrv_no_email_scope` if scope does not include `email`
  "email_verified": true
}

You should NEVER use email as the unique identifier for a user. You should ONLY use either id or sub as the unique identifier for a user because they will not change even if the user changes their email or other info.

Only the above information will be included in the JWT, if you need info such as avatar url, please send a request to the UserInfo Endpoint with the provided access token.

Text behind // are comments and are not included in the response itself

Verifying JWT Authenticity

You MUST verify the JWT (id_token) authenticity

The signature can be verified using the public key provided at the JWKS URI: https://auth.spookysrv.com/oidc/.well-known/jwks.json

When verifying the JWT, you should check:

• The iss claim MUST be equal to https://auth.spookysrv.com/oidc/

• The aud claim MUST be equal to YOUR CLIENT ID

• The exp claim date has NOT PASSED (NOT EXPIRED)

• The JWT signature is valid with the JWKs listed above

Spooky Services ONLY signs with ONE ES256 key for signature