curl -X POST "https://gachabe-staging.fly.dev/api/v1/players/refresh_token" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "player",
      "attributes": {
        "refresh_token": "refresh_token_string_here"
      },
      "relationships": {}
    }
  }'

{
  "data": {
    "type": "player",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "email": "player@example.com",
      "is_anonymous": false
    },
    "relationships": {
      "chests": {
        "data": [
          {
            "type": "chest",
            "id": "chest_001"
          }
        ]
      }
    }
  },
  "included": [],
  "meta": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "new_refresh_token_string_here",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refreshed_at": "2024-01-15T17:00:00Z",
    "previous_token_issued": "2024-01-15T16:00:00Z",
    "session_extended_until": "2024-02-14T17:00:00Z"
  }
}
Obtain a new access token using a valid refresh token. This endpoint allows you to maintain authenticated sessions without requiring the user to sign in again.
Refresh tokens have a longer lifespan than access tokens (typically 30 days vs 1 hour) and can be used multiple times until they expire.

​
Query Parameters

​
include
string
Include related data in the response.Available includes: chests
​
fields
object
Limit response fields to only those specified.

​
Request Body

​
data
object
required
Token refresh request data
curl -X POST "https://gachabe-staging.fly.dev/api/v1/players/refresh_token" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "player",
      "attributes": {
        "refresh_token": "refresh_token_string_here"
      },
      "relationships": {}
    }
  }'

{
  "data": {
    "type": "player",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "email": "player@example.com",
      "is_anonymous": false
    },
    "relationships": {
      "chests": {
        "data": [
          {
            "type": "chest",
            "id": "chest_001"
          }
        ]
      }
    }
  },
  "included": [],
  "meta": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "new_refresh_token_string_here",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refreshed_at": "2024-01-15T17:00:00Z",
    "previous_token_issued": "2024-01-15T16:00:00Z",
    "session_extended_until": "2024-02-14T17:00:00Z"
  }
}

​
Response Fields

​
data
object
required
Updated player information
​
meta
object
required
New authentication tokens and refresh metadata

​
Token Refresh Strategy

1

Monitor token expiration

Track when your access token expires and refresh proactively.
Refresh 5 minutes before expiration to avoid service interruption.
2

Implement automatic refresh

Create middleware that automatically refreshes tokens before API calls.
This ensures users never experience authentication failures.
3

Handle refresh failures

When refresh tokens are invalid or expired, redirect users to sign in.
Clear all stored tokens to prevent repeated failed refresh attempts.
4

Update stored tokens

Always replace both access and refresh tokens with the new ones from the response.
Refresh tokens are single-use and become invalid after successful refresh.

​
Refresh Token Lifecycle

Token Rotation: Each refresh operation provides both a new access token and a new refresh token. The old refresh token becomes invalid immediately.Expiration: Refresh tokens typically last 30 days from their creation date, regardless of usage frequency.Revocation: Refresh tokens are automatically revoked when a user signs out or changes their password.

​
Error Handling Strategies

Status: 401 UnauthorizedThe refresh token is malformed, invalid, or doesn’t exist.Action: Clear stored tokens and redirect to sign-in page.

​
Best Practices

Never expose refresh tokens in URLs, logs, or client-side code where they could be compromised. Treat them with the same security as passwords.
The new refresh token returned in the response should replace the old one immediately. Attempting to use an old refresh token after a successful refresh will result in an authentication error.