How PlaySmart authentication works: JWT bearer tokens

PlaySmart uses JSON Web Tokens (JWT) signed with HS256 to authenticate API requests. When you register or log in, the API returns two tokens. You send the access token with every protected request, and use the refresh token to obtain new credentials when the access token expires.

Tokens

PlaySmart issues two tokens on every successful authentication:

Token	Header claim	Expiry	Purpose
`access_token`	`Authorization: Bearer`	30 days	Authenticate API requests
`refresh_token`	—	180 days	Re-authenticate after access token expiry

The access token’s sub claim contains the player’s auth_user_id. Protected endpoints read this claim to identify the caller. The refresh token carries a kind: "refresh" claim and is used solely to issue a new access token — pass it to /auth/login or a dedicated refresh endpoint as appropriate for your integration.

Tokens are not revocable server-side. If a token is compromised, it remains valid until it expires. Treat both tokens like passwords: store them in secure, device-local storage and never log or transmit them in plain text.

Register a new player

Send a POST request to /auth/register to create a player account. The deviceId you provide becomes the player’s permanent auth_user_id and is embedded as the JWT sub claim. Request fields

string

required

A valid email address. Must be unique across all players.

string

required

The player’s password. Minimum 8 characters.

string

required

A stable, unique identifier for the player’s device. Stored as auth_user_id.

Example request

curl -X POST https://api.playsmart.io/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "player@example.com",
    "password": "hunter12345",
    "deviceId": "device-abc-123"
  }'

Example response — 201 Created

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": "device-abc-123",
      "email": "player@example.com",
      "pseudo": "",
      "total_games_completed": 0
    }
  }
}

Log in an existing player

Send a POST request to /auth/login with the player’s credentials. The response structure is identical to registration. Request fields

string

required

The player’s registered email address.

string

required

The player’s password.

Example request

curl -X POST https://api.playsmart.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "player@example.com",
    "password": "hunter12345"
  }'

Example response — 200 OK

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": "device-abc-123",
      "email": "player@example.com",
      "pseudo": "",
      "total_games_completed": 0
    }
  }
}

Using the access token

Pass the access_token in the Authorization header on every request to a protected endpoint:

curl https://api.playsmart.io/ingest/events \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

The API also accepts the token in an X-Forwarded-Authorization header, which takes precedence over Authorization when both are present.

Error responses

HTTP status	`code`	`message`	Cause
`400 Bad Request`	`BAD_REQUEST`	`invalid_payload`	Request body is missing, malformed, or fails validation (e.g. password too short, invalid email)
`401 Unauthorized`	`UNAUTHORIZED`	`invalid_credentials`	Email not found, or password does not match
`401 Unauthorized`	`UNAUTHORIZED`	`missing_bearer_token`	Protected endpoint called without an `Authorization` header
`409 Conflict`	`CONFLICT`	`email_already_registered`	A player with this email address already exists

Get Started

Core Concepts

Guides

How PlaySmart authentication works: JWT bearer tokens

Tokens

Register a new player

Log in an existing player

Using the access token

Error responses

​Tokens

​Register a new player

​Log in an existing player

​Using the access token

​Error responses

Tokens

Register a new player

Log in an existing player

Using the access token

Error responses