DocsGetting StartedAPI specificationAuthorization

Authorization Flow Implementation

Complete guide to implementing the authorization process

Authorization Flow

Authorization is the first critical step in the integration process. This flow creates a secure connection between your game, the player, and our platform.

Process Overview

  1. Your game initiates an authorization request
  2. The player authenticates through our platform
  3. Your game polls for completion status
  4. Upon successful authorization, you receive a token for subsequent API calls

Step 1: Initiate Authorization

POST /api/games/auth/initiate

This endpoint creates an authorization request and returns the necessary information to complete the process.

Request Parameters

ParameterTypeRequiredDescription
game_uuidstringYesYour game's unique identifier (use test UUID during development)
device_uuidstringNoA persistent device identifier that remains consistent across installations

Example Request

{
    "game_uuid": "404e1b2b-de1b-4988-8cc8-94239dc482b3",
    "device_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Response Structure

FieldTypeDescription
auth_idstringUnique identifier for this authorization request (store this value)
auth_urlstringURL to direct the player to for authentication

Example Response

{
    "auth_id": "d63d00da-ed78-4eba-b531-0f556e64cd4e",
    "auth_url": "https://app.playmanity.net/auth/games/authorize/d63d00da-ed78-4eba-b531-0f556e64cd4e"
}

Step 2: Poll for Authorization Status

Once you've initiated the authorization request and directed the player to the auth_url, you need to poll our API to check when the player completes the process.

POST /api/games/auth/status/[auth_id]

Poll this endpoint to check the authorization status and retrieve the auth token when available.

Request Parameters

ParameterTypeRequiredDescription
auth_idstringYesThe authorization ID received from the initiate endpoint

Response Structure

FieldTypeDescription
statusstringCurrent status: "valid", "denied", or "unresolved"
auth_tokenstring(Only present when status is "valid") The authorization token for future API calls
gamestringInternal game ID used by our platform

Example Response (Success)

{
    "status": "valid",
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "game": "123"
}

Example Response (Pending)

{
    "status": "unresolved",
    "game": "123"
}

Best Practices

  1. Polling Frequency: Poll the status endpoint every 1-2 seconds. Polling too frequently may impact performance.

  2. Token Storage: Securely store the auth_token for the duration of the game session.

  3. Error Handling: Implement proper timeout and retry logic for cases where authorization takes longer than expected.

  4. User Experience: Provide clear feedback to the player during the authorization process.

Next Steps

After successful authorization, you'll need to establish a game session before requesting advertisements. See the Session Management section for details.

PreparationsSession Management