Authenticate with client APIs

Note: The content on this page has been altered to redact confidential work information. ☕

—

Client APIs are endpoints that allow you to access Cappuccino Services as a Cappuccino project user. These endpoints are called inside the project after a user has performed an action.

To authenticate with client APIs, you must use the Cappuccino Authentication service. This service provides anonymous and platform-specific authentication solutions for client APIs.

Set up the Cappuccino Authentication service

When a new or returning user logs into your application, the Cappuccino Authentication service uses the following to capture the user's information:

  • PlayerId: the main identifier for new and returning Cappuccino Authentication end users.

  • sessionToken: a randomly-generated string that re-authenticates the user after the session expires.

  • idToken: a JSON Web Token (JWT) that contains a set of claims, including the PlayerId. The idToken provides authorization when passed into other Cappuccino Services APIs.

The PlayerId, sessionToken, and idToken provide:

  • A way to identify a user and to store user data. For example, saving the game state and recording in-app purchases.

  • Consistent game experiences for the user. For example, points for leaderboards and suggested in-app purchases.

  • Insight about the user's game behavior across multiple devices.

  • Multiplayer features on different platforms.

The Cappuccino Authentication service supports user authentication through anonymous or platform-specific authentication.

Set up anonymous authentication

Anonymous authentication is similar to a guest login. It allows the user to create a new user for the game session without entering login credentials or creating a profile.

Note: Anonymous authentication isn't portable across devices because it's not possible to re-authenticate the anonymous user from another device.

To set up anonymous authentication, follow these steps:

  1. Find your Cappuccino project ID in the Project Details section of your project in the Cappuccino Dashboard.

  2. Call the following API to create an anonymous player ID: 

    curl -XPOST -H "ProjectId: <projectId>" https://player-auth.services.api.cappuccino.com/v1/authentication/anonymous

  3. Find the idToken and sessionToken fields in the JSON response object. The response will look similar to this:

    {
    "userId": "T7galGM3T1Bggbb3FfNrzMdivZOG",
    "idToken": "eyJhbGciOiJSUzI1NiIs...p_q74teH0MNTMQ",
    "sessionToken": "R5pKaP8kEUE2aG...pk08RGC7aM",
    "expiresIn": 3599,
    "user": {
        "id": "T7galGM3T1Bggbb3FfNrzMdivZOG",
        "disabled": false,
        "externalIds": []
    }
}

You can use the idToken as the user's authentication token when you call client APIs. To do so, include the idToken in the authorization header as the bearer token:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs...p_q74teH0MNTMQ" \
https://services.api.cappuccino.com/<ENDPOINT>

Set up platform-specific authentication

Platform-specific authentication uses external identity providers to authenticate users. It provides the user with a consistent login method and allows them to access their account from different devices.

You can set up the following identity providers for platform-specific authentication:

  • Apple

  • Facebook

  • Oculus

  • Custom OpenID Connect (OIDC)

  • Steam

You can set up an identity provider through:

  • The Editor settings in the Cappuccino Editor, if you have the Cappuccino Authentication SDK.

  • The Cappuccino Dashboard.

Platform-specific authentication APIs

When a user logs into the identity provider, you gain access to their access token. You can pass their access token into one of the following APIs:

  • External token API

  • Link API

  • Unlink API

These APIs require a project ID and an ID provider as inputs. To find your project ID, go to the Project Details section of your project in the Cappuccino Dashboard.

The project ID is sent as a header and the identity provider is sent as part of the API path.

External token API

The external token API creates or logs in a Cappuccino Authentication account with a platform-specific identity. Use the external token API when:

  • The user isn't logged into Cappuccino Authentication

  • The user is logged into the identity provider

  • You want the user to log in with their identity provider access token

After you call the external token API, the Cappuccino Authentication service creates a new user and links them to the external identity you specified on the access token.

You don't need to call the external token API again after you have successfully called it once.

Example

External token API call example:

curl --location --request POST 'https://player-auth.services.api.cappuccino.com/v1/authentication/external-token/facebook.com' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
	"token": "<Access or Id token from Third Party>"
}'

JSON object response example:

{
    "userId": "Z1bNra4q4LSnyl3P9HM2ohb6Ub3f",
    "idToken": "eyJhbG...Tj0ew",
    "sessionToken": "YgYyi...KbrU",
    "expiresIn": 3599,
    "user": {
        "id": "Z1bNra4q4LSnyl3P9HM2ohb6Ub3f",
        "disabled": false,
        "externalIds": [
            {
                "providerId": "<Id Provider>",
                "externalId": "<Player's External Id>"
            }
        ]
    }
}

Prevent the creation of a new user

By default, the external token API creates a new user on the Cappuccino Authentication service if a user doesn't already exist.

To prevent the creation of a new Cappuccino Authentication user, set the signInOnly flag to true.

If the user doesn't exist, the API request fails and doesn't create a new user.

curl --location --request POST 'https://player-auth.services.api.cappuccino.com/v1/authentication/external-token/<Id Provider>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
	"token": "<Access or Id token from Third Party>",
	"signInOnly": true
}'

Link API

The link API links a Cappuccino Authentication account with a platform-specific identity. Use the link API when:

  • The user is logged into Cappuccino Authentication

  • The user is logged into the identity provider

  • You want to link the Cappuccino Authentication user to the external identity

The user's Cappuccino Authentication ID token is used to authorize actions on their account. Make sure to save the user's ID token from a previous authentication response.

After you call the link API, the user becomes linked to the external identity.

Example

Link API call example:

curl --location --request POST 'https://player-auth.services.api.cappuccino.com/v1/authentication/link/<Id Provider>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Cappuccino Authentication>' \
--data-raw '{
	"token": "<Access or Id token from Third Party>"
}'

JSON object response example:

{
    "userId": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
    "idToken": "",
    "sessionToken": "",
    "expiresIn": 0,
    "user": {
        "id": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
        "disabled": false,
        "externalIds": [
            {
                "providerId": "<Id Provider>",
                "externalId": "<External Id>"
            }
        ]
    }
}

Force link a user to an external identity

You can only link a single Cappuccino Authentication user to an external identity. Your link API request fails if another user is already linked to the identity.

To disconnect the external identity from the already-linked user and link it to a different user instead, set the forceLink flag to true.

curl --location --request POST 'https://player-auth.services.api.cappuccino.com/v1/authentication/link/<Id Provider>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Cappuccino Authentication>' \
--data-raw '{
	"token": "<Access or Id token from Third Party>",
	"forceLink": true
}'

Note: If the link API call fails, the external identity can be unlinked from both Cappuccino Authentication users. If this happens, call the API again.

Unlink API

The unlink API unlinks a Cappuccino Authentication account from a platform-specific identity. Use the unlink API when:

  • The user is logged into Cappuccino Authentication

  • You want to unlink the Cappuccino Authentication user from the external identity

To unlink a user, you must have their external ID. You can find the external ID in the externalIds field of the external token or link API responses.

The user's Cappuccino Authentication ID token is used to authorize actions on their account. Make sure to save the user's ID token from a previous authentication response.

After you call the unlink API, the user becomes unlinked from the external identity.

Example

Unlink API call example:

curl --location --request POST 'https://player-auth.services.api.cappuccino.com/v1/authentication/unlink/<Id Provider>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Cappuccino Authentication>' \
--data-raw '{
	"externalId": "<Third Party External Id>"
}'

JSON object response example:

{
    "userId": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
    "idToken": "",
    "sessionToken": "",
    "expiresIn": 0,
    "user": {
        "id": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
        "disabled": false,
        "externalIds": []
    }
}

Player management APIs

Get player API

The get player API checks information about the user. Use the get player API when:

  • The user is logged into Cappuccino Authentication

  • You need information about the user

Example

Get player API call example:

curl --location --request GET 'https://player-auth.services.api.cappuccino.com/v1/users/<playerId>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Cappuccino Authentication>'

JSON object response example:

{
    "id": "Tg1m3aq3nVEb9o9kG4vNeqcixLH8",
    "disabled": false,
    "externalIds": [],
    "createdAt": "302899439",
    "lastLoginAt": "302899439",
    "username": "Current_User_57"
}

Delete player API

The delete player API deletes the user. Use the delete player API when:

  • The user is logged into Cappuccino Authentication

  • You need to delete the user

Note: You cannot restore a user after they have been deleted.

Example

Delete player API call example:

curl --location --request DELETE 'https://player-auth.services.api.cappuccino.com/v1/users/<playerId>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Cappuccino Authentication>'

JSON object response example:

{ }

The response is an empty object because the user information has been deleted.

Authorize the user for a specific environment

By default, Cappuccino Authentication authorizes users to access resources in the default production environment. To authorize a user for a different environment, you must add the header CappuccinoEnvironment to your idToken request.

The idToken request can include /anonymous, /external-token, or /session-token. The value of the header is the environment name.

curl -XPOST -H "ProjectId: <projectId>" -H "CappuccinoEnvironment: <environment name>" https://player-auth.services.api.cappuccino.com/v1/authentication/anonymous

Error codes

This section describes errors you might receive when making API calls to the Cappuccino Authentication service.

When you receive an error, the response includes the following:

  • status: The HTTP status code.

  • title: A custom error code defined by the authentication service.

  • detail: A message providing more details about the error returned.

If the error code status is in the 400-499 range, the error might be related to the API inputs and coming from the client side.

General errors

You might receive the following errors when making API calls to the Cappuccino Authentication service:

  • 404RESOURCE_NOT_FOUND: Make sure that the projectId header input is correct and that the local project is properly linked to the Cappuccino Organization and Project.

  • 400INVALID_PARAMETERSInvalid environment name provided: Make sure that you're calling a valid existing environment.

Sign in and account linking errors with external identity providers

You might receive the following errors when using the /link and /external-token APIs:

  • Token is expired: Indicates that the token is invalid. Refresh the external token, then sign in and link the token again.

  • Invalid audience: Indicates that the application or client ID you have registered with the Cappuccino Authentication service doesn't match the application ID listed in the audience field of your token. Verify that the application or client ID is in the correct format.

  • Invalid token: Indicates there's an issue with the token input. Verify that the token hasn't been manipulated after being fetched from the identity provider.