REST API Reference

REST API Reference#

Attention

Only the endpoints listed in this section are officially supported by Rave. Other API endpoints used by the SDKs may change without notice and should not be used directly.

Overview#

When to Use the REST API#

The REST API can be used for dedicated server-side functions and scenarios not supported by the SDKs. For example, to display leaderboards on a website, use the leaderboard REST API endpoint described below to fetch the leaderboard data.

The REST API should not be used directly outside of SDK scenarios, as the SDKs provide access to the same functions. While the SDKs use additional endpoints beyond those documented here, only the endpoints listed below are officially supported for direct use.

Base URL#

The base URL for your Rave backend environment should have been given to you by your account manager and will be referenced below as (URL: base_env_url).

Same applies to your management portal link, and below it will be referenced as (URL: base_portal_url)

Error Responses#

The structure of an error response is shown below. The response has the following characteristics:

  • It is a dictionary object

  • It has an “error” key

  • The “error” key has a value that is a dictionary

  • The “error” dictionary contains the following fields:

    • message: A human-readable message. The exact wording of this may be changed in future API versions.

    • code: A code identifying the error. This value will never be changed in future API versions.

    "error": {
    "message": "The token is not valid",
    "code": 433
}

Users and Sid#

Create a Rave User and get UUID#

POST /v5/auth/register#

This outlines how to create a user that is authorized via a username or email address and a password. The post will generate the necessary records on the server side to support a user record, device and allow for it to authenticate via password auth to get a session.

Request Headers:
JSON Parameters:

  • app[uuid] (str) – The UUID for the application that the user is being registered for. This does not limit which applications the user can be used with. It is primarily used for analytics purposes

  • device[identifier] (str) – A string that describes the device and is used to identify the device when creating a session. The identifier should be unique across all the devices for a given user and must be persisted on the device.

  • device[name] (str) – An human-readable name describing the device, like “Jane’s iPad” for example. If a device name is not available, generate a human readable string, such as “iPhone 3G”. It must be between 1 and 255 characters, inclusive

  • user[birthdate] (str) – (optional) Date in ISO8601 format (YYYY-MM-DD). If the month and/or day are unknown, set the values to “01”. A minimum year of 1900 is enforced, but no upper limit is enforced. If not specified, a default value of “1900-01-01” will be set.

  • user[display_name] (str) – (optional) Desired display name. This is the name which the user interface and game should show to other users. This name does not need to be unique. Defaults to the username. The maximum length is 255 characters

  • user[email] (str) – (optional) User’s email address. The email must be be unique across all users. Password authentication requires either email or username parameter.

  • user[username] (str) – (optional) Desired username. Must be unique across all users. The username must adhere to the following rules (1) The first character must be in the set [A-Za-z] (2) The remaining characters must be from the set [A-Za-z0-9_] (3) The minimum username length is 3 characters (4) The maximum username length is 64 characters. If a username is not specified, an anonymous user with a default username will be created by the service. Password authentication requires either email or username parameter.

  • user[password] (str) – A password string, minimum of 6 characters, used to register the user with password authentication.

  • user[name] (str) – (optional) User’s full name. The maximum length is 255 characters

  • user[profile_image_url] (str) – (optional) A URL for the user’s profile image

  • user[uuid] (str) – (optional) Specify a desired UUID for the user. This must be a unique value across all users in the system, so the registration will be rejected if the specified UUID already exists in the system. If this value is not specified, the service will automatically generate a UUID for the user.

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 403: Application does not exist. An api_key that does not exist was specified.

  • 457: User with UUID already exists

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Example request:

POST /v5/auth/register HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "device": {
        "name": "MyPhon",
        "identifier": "1234567890"
    },
    "user": {
        "password": "MyPassword",
        "email": "shabadoo@springfield.com",
        "display_name": "Joey Joe Joe Shabadoo"
    },
    "source": "password",
    "app": {
        "uuid": "139adceff406467eb3ed8a9db9dd1d1a"
    }
}

Making a request with curl:

curl -X POST -H 'Content-Type: application/json' -d '{ "device": { "name": "MyPhon", "identifier": "1234567890" }, "user": { "password": "MyPassword", "email": "shabadoo@springfield.com", "display_name": "Joey Joe Joe Shabadoo" }, "source": "password", "app": { "uuid": "139adceff406467eb3ed8a9db9dd1d1a" } }' https://(URL: base_env_url)/v5/auth/register

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "created_at": "2019-01-03T21:00:30",
        "display_name": "Joey Joe Joe Shabadoo",
        "email": "shabadoo@springfield.com",
        "is_confirmed": false,
        "name": null,
        "profile_image_source": "",
        "profile_image_url": null,
        "state": "authenticated",
        "updated_at": "2019-01-03T21:00:30",
        "username": "user12038017576187291500",
        "username_state": "custom",
        "uuid": "5eb1a41b009e4415a70fa134948d676c",
        "fb_uid": null,
        "gplus_uid": null,
        "google_uid": null,
        "tw_uid": null,
        "apple_uid": null
    }
}

Create an anonymous Rave User and get UUID#

POST /v5/auth/register#

This outlines how to create an anonymous user. The post will generate the necessary records on the server side to support a user record and device.

Request Headers:
JSON Parameters:

  • app[uuid] (str) – The UUID for the application that the user is being registered for. This does not limit which applications the user can be used with. It is primarily used for analytics purposes

  • device[identifier] (str) – A string that describes the device and is used to identify the device when creating a session. The identifier should be unique across all the devices for a given user and must be persisted on the device.

  • device[name] (str) – An human-readable name describing the device, like “Jane’s iPad” for example. If a device name is not available, generate a human readable string, such as “iPhone 3G”. It must be between 1 and 255 characters, inclusive

  • user[uuid] (str) – (optional) Specify a desired UUID for the user. This must be a unique value across all users in the system, so the registration will be rejected if the specified UUID already exists in the system. If this value is not specified, the service will automatically generate a UUID for the user.

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 403: Application does not exist. An api_key that does not exist was specified.

  • 457: User with UUID already exists

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Example request:

POST /v5/auth/register HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "app": {
        "uuid": "d7d8f987e3484922a9262833a9866750"
    },
    "device" : {
        "identifier": "4c00bd86b8b48dba",
        "name": "My iPhone"
    },
    "user": {
        "uuid": "b78a62b28d414f16a063637b35c02533"
    }
}

Making a request with curl:

curl -X POST -H 'Content-Type: application/json' -d '{ "device": { "name": "My iPhone", "identifier": "4c00bd86b8b48dba" }, "user": { "uuid": "b78a62b28d414f16a063637b35c02533" }, "app": { "uuid": "139adceff406467eb3ed8a9db9dd1d1a" } }' https://(URL: base_env_url)/v5/auth/register

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "birthdate": "1900-01-01",
        "created_at": "2019-01-02T03:04:05",
        "display_name": null,
        "email": null,
        "fb_uid": null,
        "apple_uid": null,
        "gender": null,
        "gplus_uid": null,
        "is_confirmed": false,
        "name": null,
        "profile_image_source": "",
        "profile_image_url": null,
        "state": "anonymous",
        "tw_uid": null,
        "updated_at": "2019-01-02T03:04:05",
        "username": "user11557190449596736819",
        "username_state": "anonymous",
        "uuid": "b78a62b28d414f16a063637b35c02533"
    }
}

Create a session with username and password and retrieve Sid#

POST /v5/auth/sessions/password#

A session needs to be created before any other API call can be made on behalf of the user. In order to make those calls, including to get a server auth token, and application needs to submit a Sid value in the headers with each request. This method using username/email and password will create a user session and retrieve a Sid.

Request Headers:
JSON Parameters:

  • app[uuid] (str) – The UUID for the application to create a session for

  • device[identifier] (str) – A registered device identifier for the user

  • user[username] (str) – (optional) Username of user to create session for. Password authentication requires either email, uuid, or username parameter.

  • user[uuid] (str) – (optional) UUID of user to create session for. Password authentication requires either email, uuid, or username parameter.

  • user[email] (str) – (optional) User’s email address to create the session for. Password authentication requires either email or username parameter.

  • user[password] (str) – A password string, minimum of 6 characters, used to authenticate the user with password authentication.

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 401: User cannot be found

  • 402: Application cannot be found

  • 403: Device cannot be found

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

  • 211: User’s email not verified

Example request:

POST /v5/auth/sessions/password HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "device": {
        "identifier": "1234567890"
    },
    "app": {
        "uuid": "139adceff406467eb3ed8a9db9dd1d1a"
    },
    "user": {
        "password": "MyPassword",
        "email": "shabadoo@springfield.test"
    }
}

Making a request with curl:

curl -X POST  https://(URL: base_env_url)/v5/auth/sessions/password  -H 'Content-Type: application/json' -d ' { "device": { "identifier": "1234567890" }, "app": { "uuid": "139adceff406467eb3ed8a9db9dd1d1a" }, "user": { "email": "shabadoo@springfield.test", "password": "MyPassword" } }'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "sid": "a106d70b906d4680d6d49b6e664e2a90"
    }
}

Create a session with anonymous user and retrieve Sid#

POST /v5/auth/sessions#

A session needs to be created before any other API call can be made on behalf of the user. In order to make those calls, including to get a server auth token, and application needs to submit a Sid value in the headers with each request. This method will retrieve a Sid for an anonymous user.

Request Headers:
JSON Parameters:

  • app[uuid] (str) – The UUID for the application to create a session for

  • device[identifier] (str) – A registered device identifier for the user

  • user[username] (str) – (optional) Username of user to create session for. Password authentication requires either email, uuid, or username parameter.

  • user[uuid] (str) – (optional) UUID of user to create session for. Password authentication requires either email, uuid, or username parameter.

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 401: User cannot be found

  • 402: Application cannot be found

  • 403: Device cannot be found

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

  • 211: User’s email not verified

Example request:

POST /v5/auth/sessions HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "app": {
        "uuid": "d7d8f987e3484922a9262833a9866750"
    },
    "device" : {
        "identifier": "4c00bd86b8b48dba"
    },
    "user": {
        "uuid": "b78a62b28d414f16a063637b35c02533"
    }
}

Making a request with curl:

curl -X POST  https://(URL: base_env_url)/v5/auth/sessions  -H 'Content-Type: application/json' -d ' { "device": { "identifier": "1234567890" }, "app": { "uuid": "139adceff406467eb3ed8a9db9dd1d1a" }, "user": { "uuid": "b78a62b28d414f16a063637b35c02533" } }'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "sid": "a106d70b906d4680d6d49b6e664e2a90"
    }
}

Email OTP Authentication#

The Email OTP Authentication API provides a versatile method for both account access and recovery. It allows users to authenticate their identity using an OTP sent to their verified email, applicable for both logging into their account and recovering access if the primary authentication method (e.g., Passkey) is unavailable.

Email OTP Authentication Endpoints#

Request OTP#

POST /v5/auth/sessions/email/otp#

Initiates the authentication process by requesting an one-time password (OTP), which is sent to the user’s verified email address. This step verifies that the user has access to the email account linked with their Rave profile.

Request Headers:
JSON Parameters:

  • email (str) – The user’s email address.

Status Codes:

  • 200 OK – The request was processed without problems.

Errors

  • 211: User’s email not verified

  • 226: Email OTP Auth requires a passkey previously setup

  • 401: User cannot be found

  • 700: Invalid request parameters

  • 760: Missing required parameters

Example request:

POST /v5/auth/sessions/email/otp HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "email": "user@example.com"
}

Making a request with curl:

curl -X POST https://(URL: base_env_url)/v5/auth/sessions/email/otp -H 'Content-Type: application/json' -d '{"email": "user@example.com"}'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "OTP sent to user@example.com"
}

Verify OTP#

POST /v5/auth/sessions/email/otp/verify#

Validates the OTP provided by the user. Upon successful verification, a session ID is created, granting the user access to their account.

Request Headers:
JSON Parameters:

  • user[email] (str) – The user’s email address.

  • otp (str) – The One-Time Password to verify.

  • app[uuid] (str) – The UUID of the application associated with this session.

Status Codes:

  • 200 OK – The request was processed without problems.

Errors

  • 206: Invalid or expired OTP code

  • 402: Application not found

  • 700: Invalid request parameters

  • 760: Missing required parameters

Example request:

POST /v5/auth/sessions/email/otp/verify HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "user": {
        "email": "user@email.com"
    },
    "otp": "123456",
    "app": {
        "uuid": "d7d8f987e3484922a9262833a9866750"
    }
}

Making a request with curl:

curl -X POST https://(URL: base_env_url)/v5/auth/sessions/email/otp/verify -H 'Content-Type: application/json' -d '{"user": {"email": "user@email.com"}, "otp": "123456", "app": {"uuid": "d7d8f987e3484922a9262833a9866750"}}'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "sid": "a106d70b906d4680d6d49b6e664e2a90"
    }
}

Passkey Authentication#

The Passkey Authentication API leverages the Web Authentication (WebAuthn) standard to provide a secure, public key-based credential system for user authentication. Below you will find the endpoints required for integrating Passkeys, including registration, authentication, and passkey management processes.

Settings for the Passkey feature can be customized via the Rave Management Portal API settings.

Important

All Passkey API interactions must occur over HTTPS. The system enforces input validation, error handling, and CSRF protection on all API calls to ensure security and integrity.

Registration Endpoints#

Registration Initiation#

POST /auth/register/passkey/initiate#

Initiates the Passkey registration ceremony for new users by providing the necessary credential options as per the WebAuthn specification.

Request Headers:
JSON Parameters:

  • user[email] (str) – User’s email address. This is a required field.

  • user[display_name] (str) – (optional) The visual representation of the user, defaults to their email.

Status Codes:

  • 200 OK – The request was processed without problems.

Example request:

{
  "user": {
    "email": "johndoe2@email.com"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "state": "e8d91f11a1754837a9f645a163a9d737",
    "options": {
      "challenge": "vO62LaaAypm7xnqZCkhb_JWIcWnO_uoOAubPBCpVD9sj5Pdao2XN4XiSQgejrtpyw6yhAYRC0_Oi6TU5rEiJIw",
      "rp": {
        "name": "Rave Social",
        "id": "rave-eng.com"
      },
      "user": {
        "id": "ZjRlM2YwNDljZTZhNDk2NDg1MjdlYTU0ZDMwZjRkMmY",
        "name": "johndoe@email.com",
        "displayName": "johndoe@email.com"
      },
      "pubKeyCredParams": [
        {
          "type": "public-key",
          "alg": -7
        },
        {
          "type": "public-key",
          "alg": -8
        },
        {
          "type": "public-key",
          "alg": -36
        },
        {
          "type": "public-key",
          "alg": -37
        },
        {
          "type": "public-key",
          "alg": -38
        },
        {
          "type": "public-key",
          "alg": -39
        },
        {
          "type": "public-key",
          "alg": -257
        },
        {
          "type": "public-key",
          "alg": -258
        },
        {
          "type": "public-key",
          "alg": -259
        }
      ],
      "timeout": 60000,
      "excludeCredentials": [],
      "attestation": "none"
    }
  }
}

Errors

  • 101: Invalid Passkey Configuration

  • 441: User Already Exists

  • 700: Invalid request parameters

  • 760: Missing required parameters

Registration Completion#

POST /auth/register/passkey/verify#

Finalizes the Passkey registration process and securely stores the new Passkey.

Request Headers:
JSON Parameters:

  • app[uuid] (str) – The UUID for the application that the user is being registered for. This does not limit which applications the user can be used with. It is primarily used for analytics purposes

  • device[identifier] (str) – A string that describes the device and is used to identify the device when creating a session. The identifier should be unique across all the devices for a given user and must be persisted on the device.

  • device[name] (str) – An human-readable name describing the device, like “Jane’s iPad” for example. If a device name is not available, generate a human readable string, such as “iPhone 3G”. It must be between 1 and 255 characters, inclusive

  • user[birthdate] (str) – (optional) Date in ISO8601 format (YYYY-MM-DD). If the month and/or day are unknown, set the values to “01”. A minimum year of 1900 is enforced, but no upper limit is enforced. If not specified, a default value of “1900-01-01” will be set.

  • user[display_name] (str) – (optional) Desired display name. This is the name which the user interface and game should show to other users. This name does not need to be unique. Defaults to the username. The maximum length is 255 characters

  • user[email] (str) – User’s email address. The email must be be unique across all users.

  • user[username] (str) – (optional) Desired username. Must be unique across all users. The username must adhere to the following rules (1) The first character must be in the set [A-Za-z] (2) The remaining characters must be from the set [A-Za-z0-9_] (3) The minimum username length is 3 characters (4) The maximum username length is 64 characters. If a username is not specified, an anonymous user with a default username will be created by the service.

  • user[name] (str) – (optional) User’s full name. The maximum length is 255 characters

  • user[given_name] (str) – (optional) User’s given name. The maximum length is 255 characters

  • user[family_name] (str) – (optional) User’s family name. The maximum length is 255 characters

  • user[profile_image_url] (str) – (optional) A URL for the user’s profile image

  • user[uuid] (str) – (optional) Specify a desired UUID for the user. This must be a unique value across all users in the system, so the registration will be rejected if the specified UUID already exists in the system. If this value is not specified, the service will automatically generate a UUID for the user.

  • state (str) – The state token received from the initiation response.

  • passkey_name (str) – (optional) The name to be given as visual representation of the passkey credential.

  • passkey (object) – Passkey data including user ID, passkey ID, raw passkey ID, and authenticator response data.

Status Codes:

  • 200 OK – The request was processed without problems.

Example request:

{
  "user": {
    "email": "johndoe@email.com"
  },
  "app": {
    "uuid": "139adceff406467eb3ed8a9db9dd1d1a"
  },
  "device": {
    "identifier": "test_api",
    "name": "Test API"
  },
  "state": "0b493b8aac614625bfed16cce999a2e8",
  "passkey_name": "Chrome",
  "passkey": {
    "id": "i867jWNn40tTImaRYUcz_CJUz3hfbQH7oLI66oJYVHo",
    "rawId": "i867jWNn40tTImaRYUcz_CJUz3hfbQH7oLI66oJYVHo",
    "response": {
      "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVikvoo_Jv56yBTa7LaDAMM7mzYQvR3vgYn4b7sdcaGa48NFAAAAAK3OAAI1vMYKZIsLJfHwVQMAIIvOu41jZ-NLUyJmkWFHM_wiVM94X20B-6CyOuqCWFR6pQECAyYgASFYIEAj7khIezY-xdQGLMrYmtO9GLXItKYwtaQ1pK4KWvznIlggGP6046i5c2PPHSH_lZFQI9CSo8g-lOF422Z8g11pDTo",
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiX2lSX1VKTS02V0IwOEV5dE5iak5MSmlYcE5NeFZ2eGFLTkozMU9MMVRoajlRcm5vS0hrNEhFTWpVbHpMNmlTSVNXd1ZWTlFvUnV0dGRzdGNVT1F3bVEiLCJvcmlnaW4iOiJodHRwczovL3Bhc3NrZXktdGVzdC5yYXZlLWVuZy5jb20iLCJjcm9zc09yaWdpbiI6ZmFsc2V9",
      "transports": [
        "internal"
      ],
      "publicKeyAlgorithm": -7,
      "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQCPuSEh7Nj7F1AYsytia070Ytci0pjC1pDWkrgpa_OcY_rTjqLlzY88dIf-VkVAj0JKjyD6U4XjbZnyDXWkNOg",
      "authenticatorData": "voo_Jv56yBTa7LaDAMM7mzYQvR3vgYn4b7sdcaGa48NFAAAAAK3OAAI1vMYKZIsLJfHwVQMAIIvOu41jZ-NLUyJmkWFHM_wiVM94X20B-6CyOuqCWFR6pQECAyYgASFYIEAj7khIezY-xdQGLMrYmtO9GLXItKYwtaQ1pK4KWvznIlggGP6046i5c2PPHSH_lZFQI9CSo8g-lOF422Z8g11pDTo"
    },
    "type": "public-key",
    "clientExtensionResults": {},
    "authenticatorAttachment": "platform"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "user": {
      "birthdate": "1900-01-01",
      "created_at": "2024-03-14T00:20:54",
      "display_name": null,
      "email": "johndoe@email.com",
      "gender": null,
      "is_confirmed": false,
      "name": null,
      "given_name": null,
      "family_name": null,
      "profile_image_source": "",
      "profile_image_url": null,
      "updated_at": "2024-03-14T00:20:54",
      "state": "authenticated",
      "username": "user13236871988078380358",
      "username_state": "custom",
      "uuid": "03ad381b61db4c0cb7b2d0f0f2bb0546",
      "fb_uid": null,
      "gplus_uid": null,
      "google_uid": null,
      "wallet_addresses": [],
      "tw_uid": null,
      "has_otp": false,
      "apple_uid": null
    },
    "device": {
      "name": "Test API",
      "uuid": "1b3f12b76cff428ab97ef02c338874fd",
      "identifier": "test_api",
      "created_at": "2024-03-14T00:20:54",
      "updated_at": "2024-03-14T00:20:54",
      "is_valid": true
    },
    "session": {
      "sid": "63edf3c67bd4417db06dd6b9b3637315"
    }
  }
}

Errors

  • 101: Invalid Passkey Configuration

  • 223: Passkey Verification Failed

  • 224: Invalid or Expired State Token

  • 402: Application not found

  • 441: User Already Exists

  • 700: Invalid request parameters

  • 760: Missing required parameters

Authentication Endpoints#

Authentication Initiation#

POST /auth/sessions/passkey/initiate#

Starts the authentication process for users with a registered Passkey.

Request Headers:
JSON Parameters:

  • user[email] (str) – (optional) the user’s email address to retrieve existing allowed credentials.

Status Codes:

  • 200 OK – The request was processed without problems.

Example request:

{
  "user": {
    "email": "johndoe@email.com"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "state": "afb57b8a5eac4c5d841dc9a69d045f3a",
    "options": {
      "challenge": "kIkLU52marzh6g1tbY0zp57JLF_2khO4U9PIwRcrm8w807Yruk3TL6XX5jxjKAtipRGbjRzu_o8yLtl9JLogbw",
      "allowCredentials": [
        {
          "id": "i867jWNn40tTImaRYUcz_CJUz3hfbQH7oLI66oJYVHo",
          "type": "public-key"
        }
      ],
      "timeout": 60000,
      "userVerification": "required",
      "rpId": "rave-eng.com"
    }
  }
}

Errors

  • 101: Invalid Passkey Configuration

  • 401: User not found

  • 700: Invalid request parameters

  • 760: Missing required parameters

Authentication Completion#

POST /auth/sessions/passkey/verify#

Completes the authentication process by verifying the signed challenge.

Request Headers:
JSON Parameters:

  • app[uuid] (str) – The UUID for the application to create a session for

  • device[identifier] (str) – A registered device identifier for the user

  • state (str) – The state token received from the initiation response.

  • passkey (object) – The passkey data including the user ID, and the response data.

Status Codes:

  • 200 OK – The request was processed without problems.

Example request:

{
  "app": {
    "uuid": "139adceff406467eb3ed8a9db9dd1d1a"
  },
  "device": {
    "identifier": "test_api"
  },
  "state": "afb57b8a5eac4c5d841dc9a69d045f3a",
  "passkey": {
    "id": "i867jWNn40tTImaRYUcz_CJUz3hfbQH7oLI66oJYVHo",
    "rawId": "i867jWNn40tTImaRYUcz_CJUz3hfbQH7oLI66oJYVHo",
    "response": {
      "authenticatorData": "voo_Jv56yBTa7LaDAMM7mzYQvR3vgYn4b7sdcaGa48MFAAAAAA",
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoia0lrTFU1Mm1hcnpoNmcxdGJZMHpwNTdKTEZfMmtoTzRVOVBJd1Jjcm04dzgwN1lydWszVEw2WFg1anhqS0F0aXBSR2JqUnp1X284eUx0bDlKTG9nYnciLCJvcmlnaW4iOiJodHRwczovL3Bhc3NrZXktdGVzdC5yYXZlLWVuZy5jb20iLCJjcm9zc09yaWdpbiI6ZmFsc2UsIm90aGVyX2tleXNfY2FuX2JlX2FkZGVkX2hlcmUiOiJkbyBub3QgY29tcGFyZSBjbGllbnREYXRhSlNPTiBhZ2FpbnN0IGEgdGVtcGxhdGUuIFNlZSBodHRwczovL2dvby5nbC95YWJQZXgifQ",
      "signature": "MEYCIQCQTzopHlYSsOVHDWud-jy-1yOPtnIPgXrPkOlG4qb08AIhAOmTXKB91f0bqYwkh6bw6kju-CHje993ZqmA6mc3XLbH",
      "userHandle": "YWQwNDc2ZjFiYmI1NDhhMmJmNWZhMmMwMzlhY2E3MTE"
    },
    "type": "public-key",
    "clientExtensionResults": {},
    "authenticatorAttachment": "platform"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "session": {
      "sid": "69edf3c67bd4417da06dd6b9b363ab25"
    },
    "user": {
      "birthdate": "1900-01-01",
      "created_at": "2024-03-14T00:20:54",
      "display_name": null,
      "email": "johndoe@email.com",
      "gender": null,
      "is_confirmed": false,
      "name": null,
      "given_name": null,
      "family_name": null,
      "profile_image_source": "",
      "profile_image_url": null,
      "state": "authenticated",
      "updated_at": "2024-03-14T00:20:54",
      "username": "user13236871988078380358",
      "username_state": "custom",
      "uuid": "03ad381b61db4c0cb7b2d0f0f2bb0546",
      "fb_uid": null,
      "gplus_uid": null,
      "google_uid": null,
      "tw_uid": null,
      "apple_uid": null,
      "has_otp": false,
      "wallet_addresses": []
    }
  }
}

Errors

  • 101: Invalid Passkey Configuration

  • 223: Passkey Verification Failed

  • 224: Invalid or Expired State Token

  • 402: Application not found

  • 422: Passkey Credential not found

  • 700: Invalid request parameters

  • 760: Missing required parameters

Passkey Management Endpoints#

Connection Initiation#

GET /me/passkeys/connect#

Initiates the ceremony for adding a new Passkey to the user’s account, facilitating the enrollment of new Passkey devices.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

Status Codes:

  • 200 OK – The request was processed without problems.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "state": "558f9d550dc54d41b8e580a5a1dce9e3",
    "options": {
      "challenge": "oPvhxdhldF7RsuA6SSFoyUc8ekdx1dwJ4qF8_CfeD1n0twHNlu5o0SEzzL1aUbaN4a67Ac0Ekn5LDmtwoNnfMg",
      "rp": {
        "name": "Rave Social",
        "id": "rave-eng.com"
      },
      "user": {
        "id": "ZWM1MjkxMzMwMjA1NDFlOTliOWM3MzcyMDJmNWY5YTc",
        "name": "johndoe@email.com",
        "displayName": "johndoe@email.com"
      },
      "pubKeyCredParams": [
        {
          "type": "public-key",
          "alg": -7
        },
        {
          "type": "public-key",
          "alg": -8
        },
        {
          "type": "public-key",
          "alg": -36
        },
        {
          "type": "public-key",
          "alg": -37
        },
        {
          "type": "public-key",
          "alg": -38
        },
        {
          "type": "public-key",
          "alg": -39
        },
        {
          "type": "public-key",
          "alg": -257
        },
        {
          "type": "public-key",
          "alg": -258
        },
        {
          "type": "public-key",
          "alg": -259
        }
      ],
      "timeout": 60000,
      "excludeCredentials": [],
      "attestation": "none"
    }
  }
}

Errors

  • 101: Invalid Passkey Configuration

  • 700: Invalid request parameters

  • 760: Missing required parameters

Connection Completion#

POST /me/passkeys/connect#

Completes the process of adding a new Passkey device to the user’s account.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

JSON Parameters:

  • state (str) – The state token received from the initiation response.

  • passkey_name (str) – (optional) The name to be given as visual representation of the passkey credential.

  • passkey (object) – The passkey data including the passkey ID, and the attestation response.

  • invalidate_existing (boolean) –

    (optional) Remove all existing passkeys associated with the user’s account upon successful connect.

    Warning

    The invalidate_existing parameter must be used with caution. Setting this parameter will permanently remove all existing passkeys associated with the user’s account upon successful setup of the new one. This action is irreversible and is advisable only under circumstances where the user intends to revoke access from all previously established passkeys, such as when they are lost or compromised.

Status Codes:

  • 200 OK – The request was processed without problems.

Example request:

{
  "state": "558f9d550dc54d41b8e580a5a1dce9e3",
  "passkey_name": "Chrome",
  "passkey": {
    "id": "yZ3yXv9l4r7_9F4YHZzcYCJRtB71ZksR5V94_dcV9iM",
    "rawId": "yZ3yXv9l4r7_9F4YHZzcYCJRtB71ZksR5V94_dcV9iM",
    "response": {
      "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVikvoo_Jv56yBTa7LaDAMM7mzYQvR3vgYn4b7sdcaGa48NFAAAAAK3OAAI1vMYKZIsLJfHwVQMAIMmd8l7_ZeK-__ReGB2c3GAiUbQe9WZLEeVfeP3XFfYjpQECAyYgASFYIOMBIOh7yMhb92FX9C9yaSkAZHo5Mp_vQ_d7JyzZw3jhIlgg8iyEykQlzEZYdPe9c6TujOj6WMErw7JnG32Sd3W4B6E",
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoib1B2aHhkaGxkRjdSc3VBNlNTRm95VWM4ZWtkeDFkd0o0cUY4X0NmZUQxbjB0d0hObHU1bzBTRXp6TDFhVWJhTjRhNjdBYzBFa241TERtdHdvTm5mTWciLCJvcmlnaW4iOiJodHRwczovL3Bhc3NrZXktdGVzdC5yYXZlLWVuZy5jb20iLCJjcm9zc09yaWdpbiI6ZmFsc2V9",
      "transports": [
        "internal"
      ],
      "publicKeyAlgorithm": -7,
      "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE4wEg6HvIyFv3YVf0L3JpKQBkejkyn-9D93snLNnDeOHyLITKRCXMRlh0971zpO6M6PpYwSvDsmcbfZJ3dbgHoQ",
      "authenticatorData": "voo_Jv56yBTa7LaDAMM7mzYQvR3vgYn4b7sdcaGa48NFAAAAAK3OAAI1vMYKZIsLJfHwVQMAIMmd8l7_ZeK-__ReGB2c3GAiUbQe9WZLEeVfeP3XFfYjpQECAyYgASFYIOMBIOh7yMhb92FX9C9yaSkAZHo5Mp_vQ_d7JyzZw3jhIlgg8iyEykQlzEZYdPe9c6TujOj6WMErw7JnG32Sd3W4B6E"
    },
    "type": "public-key",
    "clientExtensionResults": {},
    "authenticatorAttachment": "platform"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "yZ3yXv9l4r7_9F4YHZzcYCJRtB71ZksR5V94_dcV9iM",
    "name": "Chrome",
    "last_used_at": "2024-03-14T00:41:35",
    "created_at": "2024-03-14T00:41:35"
  }
}

Errors

  • 101: Invalid Passkey Configuration

  • 205: Invalid authentication token

  • 223: Passkey Verification Failed

  • 224: Invalid or Expired State Token

  • 700: Invalid request parameters

  • 760: Missing required parameters

Passkey Credential Listing#

GET /me/passkeys#

Retrieves a list of all Passkey credentials associated with the current user’s account.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

Status Codes:

  • 200 OK – The request was processed without problems.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "credentials": [
      {
        "id": "HMbzWI7MbAoDQiKf80wxe8QBvxKhWxt6KBwfghz2kNQ",
        "name": "Chrome",
        "last_used_at": "2024-03-14T00:35:05",
        "created_at": "2024-03-14T00:35:05"
      }
    ]
  }
}

Errors

  • 205: Invalid authentication token

  • 700: Invalid request parameters

  • 760: Missing required parameters

Passkey Credential Removal#

DELETE /me/passkeys#

Deletes all Passkey credentials associated with the user’s account.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

Status Codes:

  • 200 OK – The request was processed without problems.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "credentials": []
  }
}

Errors

  • 205: Invalid authentication token

  • 700: Invalid request parameters

  • 760: Missing required parameters

Two Factor Authentication (2FA)#

Setup Two Factor Authentication (2FA) via One Time Password (OTP)#

Rave supports protecting accounts via Two Factor Authentication using a One Time Password application such as Google Authenticator or Authy. Our current implementation of OTP follows RFC 4226 (HOTP: An HMAC-Based One-Time Password Algorithm) and in RFC 6238 (TOTP: Time-Based One-Time Password Algorithm).

At the moment, only TOTP is supported via authenticator applications like Google Authenticator or Authy. We will be supporting HOTP in the future using SMS or Voice, but may require additional costs to cover telephony gateway charges.

Warning

User OTP configuration is global for all applications withing a customer’s account. Enabling OTP on an application that isn’t prepared to support OTP will prevent users with OTP enabled on their account from successfully signing in. This option should only be enabled after an application has integrated the proper OTP support.

To enable OTP for an application:

  1. Log into your Rave Management Portal.

  2. Find the app you would like to enable OTP on the “Apps” tab, and click on its “Settings” tab.

  3. On the Application Details page, click on the “Edit application settings” button.

  4. Check the option “Enforce OTP second factor authentication” on the “Modify Application” window.

  5. Click the “Save” button

Endpoints for managing User OTP settings#

GET /v5/me/totp/provisioning#

Generate provisioning URI used to generate QR code.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

  • Use-Token – Always set to True

Status Codes:

  • 200 OK – The request was processed without problems

Example request:

GET /v5/me/totp/provisioning HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Sid: 10000000000000000000000000000001
Use-Token: True
Timestamp: 1616694227

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "provisioning_uri": "otpauth://totp/Rave:demo%40rave.com?secret=JBSWY3DPEHPK3PXP&issuer=Rave",
        "secret": "JBSWY3DPEHPK3PXP"
    }
}
POST /v5/me/totp/provisioning#

Verify code against last generated provisioning URI and enable two-factor authentication. It will respond with a collection of Backup Codes.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

  • Use-Token – Always set to True

JSON Parameters:

  • code (str) – The 6 digits code generated from the QR code URI using a TOTP application.

  • secret (str) – The 16 digit secret generated from using the GET provisioning Endpoint.

Example request:

POST /v5/me/totp/provisioning HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Sid: 10000000000000000000000000000001
Use-Token: True
Timestamp: 1616694227

{
"code": "316439",
"secret": "JBSWY3DPEHPK3PXP"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "backup_codes": [
        "Sj1xFZiU59",
        "HacKdExOkC",
        "RzyOJK8UAr",
        "KMJDaK98jh",
        "jKV80XU5ir",
        "RPwZgoGfuv",
        "bb7NrHuMx5",
        "tC1yDInXWy",
        "FX2XHUynVj",
        "k6amPBtj0s"
    ]
}
Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 121: Anonymous user cannot use this functionality.

  • 206: Invalid code supplied.

DELETE /v5/me/totp#

Remove two-factor authentication.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

  • Use-Token – Always set to True

JSON Parameters:

  • code (str) – The 6 digits code generated from the QR code URI using a TOTP application.

  • secret (str) – The 16 digit secret generated from using the GET provisioning Endpoint.

Example request:

DELETE /v5/me/totp HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Sid: 10000000000000000000000000000001
Use-Token: True
Timestamp: 1616694227

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": true
}
Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 206: Invalid code supplied.

GET /v5/me/backup_codes#

Get existing backup codes and generate new set if there is no existing code.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

  • Use-Token – Always set to True

Status Codes:

  • 200 OK – The request was processed without problems

Example request:

GET /v5/me/backup_codes HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Sid: 10000000000000000000000000000001
Use-Token: True
Timestamp: 1616694227

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "backup_code_ts": 1575346119,
    "backup_codes": [
        "Sj1xFZiU59",
        "HacKdExOkC",
        "RzyOJK8UAr",
        "KMJDaK98jh",
        "jKV80XU5ir",
        "RPwZgoGfuv",
        "bb7NrHuMx5",
        "tC1yDInXWy",
        "FX2XHUynVj",
        "k6amPBtj0s"
    ]
}

Errors

  • 121: Anonymous user cannot use this functionality.

POST /v5/me/backup_codes#

Invalidate previous generated backup codes if there is any and generate a new set of codes.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

  • Use-Token – Always set to True

Status Codes:

  • 200 OK – The request was processed without problems

Example request:

POST /v5/me/backup_codes HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Sid: 10000000000000000000000000000001
Use-Token: True
Timestamp: 1616694227

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "backup_code_ts": 1575346119,
    "backup_codes": [
        "Sj1xFZiU59",
        "HacKdExOkC",
        "RzyOJK8UAr",
        "KMJDaK98jh",
        "jKV80XU5ir",
        "RPwZgoGfuv",
        "bb7NrHuMx5",
        "tC1yDInXWy",
        "FX2XHUynVj",
        "k6amPBtj0s"
    ]
}

Errors

  • 121: Anonymous user cannot use this functionality.

Extended Authentication Endpoints when OTP is enabled#

When an application has OTP enabled, the Create Session Endpoints has these additional API features and requirements.

POST /v5/me/auth/sessions/(str: auth_provider)#

Create a session using the Authentication Provider specified by auth_provider. If user has OTP enrolled it must provide either a valid otp code or a backup code. If both are provided the otp code takes precedence. The backup code gets invalidated once it’s used.

When authenticating users, to determine if a user requires OTP, first perform a normal Create Session request. If the response contains the Rave error code 207 then the user requires OTP in order to authenticate. This response can be used to render a form option to provide their OTP code or Backup code.

Request Headers:
JSON Parameters:

  • otp_code (str) – (optional) The 6 digits code generated from the QR code URI using a TOTP application

  • backup_code (str) – (optional) A 10 digit backup code that was provided when OTP was enabled for the user. This can be used instead of otp_code

Status Codes:

  • 200 OK – The request was processed without problems

Example request:

POST /v5/me/auth/sessions/facebook HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "facebook": {
        "token": "CAACEdEose0cBAGkUgTPNy2ASWwHBCh"
    },
    "app": {
        "uuid": "139adceff406467eb3ed8a9db9dd1d1a"
    }
    "device": {
        "name": "MyPhon",
        "identifier": "1234567890"
    },
    "otp_code": "524132"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "sid": "8834f8a975dc43409c8f8e286819fa5f"
}

Errors

  • 121: Anonymous user cannot use this functionality.

  • 206: Invalid otp code supplied.

  • 207: Otp code required.

  • 208: Invalid backup code supplied.

Tokens#

The token REST API allows Rave user tokens to be verified from a server. The tokens can be used to verify a user’s identity server-side.

GET /v5/me/token#

Create a new token or retrieve the current token for a user.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

  • Use-Token – Always set to True

Status Codes:

  • 200 OK – The request was processed without problems

Example request:

GET /v5/me/token HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Sid: 10000000000000000000000000000001
Use-Token: True
Timestamp: 1616694227

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
        "data": {
                "token": "AfMKB1NI-0TysyMpdPCUa-dgZjYCpYn01hoxfQcmCeUgKjgwj1jop6chEN-1DhORN4UzpUFC0Aw8L48K62_RjphhAe_1bxH5KD8tUug.hhrG3JHvaItK5eDb-GQDAw8-BUM"
        }
}
GET /v5/me/token/(str: user_token)#

Validates an existing token.

Request Headers:

  • Content-Type – must be set to application/json

  • Sid – User session ID

  • Timestamp – Current timestamp (Time interval since 1970)

  • Use-Token – Always set to True

Status Codes:

  • 200 OK – The request was processed without problems

Example request:

GET /v5/token/AfMKB1NI-0TysyMpdPCUa-dgZjYCpYn01hoxfQcmCeUgKjgwj1jop6chEN-1DhORN4UzpUFC0Aw8L48K62_RjphhAe_1bxH5KD8tUug.hhrG3JHvaItK5eDb-GQDAw8-BUM HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Sid: 10000000000000000000000000000001
Use-Token: True
Timestamp: 1616694227

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "app_uuid": "139adceff406467eb3ed8a9db9dd1d1a",
        "created": "2020-01-23T45:01:23",
        "expires": "2020-01-30T45:01:23",
        "is_valid": true,
        "user_uuid": "d6a1b136066e41c2ed430e28b5f00524"
    }
}

Leaderboards#

The leaderboard REST API provides access to data from Rave leaderboards.

Response Format#

There are two primary response formats - one for a successful request and one reporting an error.

Successful response#

The structure of a successful response is shown below. The response has the following characteristics:

  • It is a dictionary object

  • It has a “data” key whose value is a dictionary

  • The “data” dictionary contains a “scores” key whose value is a list of dictionary objects that provide information about each leaderboard entry in the response

  • The dictionary objects in the “scores” list contains the following keys:

    • position: An integer indicating the position of the user in the leaderboard

    • score: A floating point number with the score of the user.

    • user: A dictionary containing information about the user. The keys in this dictionary are:

      • display_name: The user’s display name

      • uuid: The user’s Rave ID

      • profile_image_url: A URL to the user’s profile image. This is an empty string if the user does not have a profile image set

    {
    "data": {
        "scores": [
            {
                "position": 7,
                "score": 5000.0,
                "user": {
                    "display_name": "Joe Smith",
                    "uuid": "a739b1b52e554e34b75cbf8301384022",
                    "profile_image_url": "http://graph.facebook.com/123/picture"
                }
            },
            {
                "position": 8,
                "score": 4000.0,
                "user": {
                    "display_name": "Jane Jones",
                    "uuid": "73d537aadff44a308b25d62d026e3260",
                    "profile_image_url": ""
                }
            },
            {
                "position": 9,
                "score": 3000.0,
                "user": {
                    "display_name": "Bob Miller",
                    "uuid": "377babad35734edbb1e5014a3fc1b1cf",
                    "profile_image_url": "http://graph.facebook.com/456/picture"
                }
            }
        ]
    }
}
Error response#

The structure of an error response is shown below. The response has the following characteristics:

  • It is a dictionary object

  • It has an “error” key

  • The “error” key has a value that is a dictionary

  • The “error” dictionary contains the following fields:

    • message: A human-readable message. The exact wording of this may be changed in future API versions.

    • code: A code identifying the error. This value will never be changed in future API versions.

    {
    "error": {
        "message": "Leaderboard definition cannot be found.",
        "code": 406
    }
}

Fetch a Page of Leaderboard Data#

GET /v5/applications/(uuid: api_key)/leaderboards/(str: leaderboard_key)/scores#

Returns a list of scores for the leaderboard with the leaderboard_key key in the application with the specified api_key. You must specify one of the following query parameters to select an offset in the leaderboards for scores that are returned:

  • page

  • score

  • user_uuid

Scores can either be returned as pages or as a range of scores adjacent to the given user or score in the leaderboard. Use the page_size and adjacent query parameters to select the desired range.

Offset selector

Range selector

Result

page

page_size

Positions ((page-1) * page_size) + 1 to (page * page_size)

page

adjacent

N/A

score

page_size

Positions ((page-1) * page_size) + 1 to (page * page_size), where page is the page that score falls in

score

adjacent

The adjacent number of scores before and after score. If score is within adjacent spots of the top or bottom of the leaderboard, less than (2 * adjacent) + 1) scores will be returned

user_uuid

page_size

Positions ((page-1) * page_size) + 1 to (page * page_size), where page is the page that user_uuid’s score is in

user_uuid

adjacent

The adjacent number of scores before and after user_uuid’s score. If this score is within adjacent spots of the top or bottom of the leaderboard, less than (2 * adjacent) + 1) scores will be returned

Example request:

GET /v5/applications/0123456789abcdef0123456789abcdef/leaderboards/lead1/scores HTTP/1.1
Host: (URL: base_env_url)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{"data": {"scores": [{"position": 7,"score": 5000.0,"user": {"display_name": "Joe Smith","uuid": "a739b1b52e554e34b75cbf8301384022","profile_image_url": "http://graph.facebook.com/123/picture"}},{"position": 8,"score": 4000.0,"user": {"display_name": "Jane Jones","uuid": "73d537aadff44a308b25d62d026e3260","profile_image_url": ""}},{"position": 9,"score": 3000.0,"user": {"display_name": "Bob Miller","uuid": "377babad35734edbb1e5014a3fc1b1cf","profile_image_url": "http://graph.facebook.com/456/picture"}}]}}
Query Parameters:

  • page – A positive integer that selects a page of scores to return.

  • user_uuid – A user UUID that selects the offset of scores to return.

  • score – A score that selects the offset of scores to return. The closest score to the specified value will be used to determine the offset if the exact score does not exist.

  • page_size – The size of the page to return. Must be in the range from 1 to 50. The default is 10.

  • adjacent – The number of adjacent scores before and after the specified score to return. Must be in the range from 0 to 100. The default is 5.

Status Codes:

  • 200 OK – The request was processed without problems

  • 404 Not Found – The request arguments were impromper. For example, the api_key was not a 32-digit hex number.

Errors

  • 401: User does not exist. A user_uuid that does not exist was specified.

  • 402: Application does not exist. An api_key that does not exist was specified.

  • 406: Leaderboard does not exist. A leaderboard_key that does not exist was specified.

  • 700: A validation error occurred. See the error message for the offending argument.

User Info From Token#

Get Rave ID from a token#

POST /v5/server/token/user#

For valid tokens, returns the Rave ID and app that the token is associated with, as well as expiration and creation times for the token.

Example request:

POST /v5/server/token/user HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "token": "AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc",
    "app": {
        "uuid": "139adceff406467eb3ed8a9db9dd1d1a"
    }
}

Making a request with curl:

curl -X POST -H 'Content-Type: application/json' -d '{ "token": "AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc", "app": { "uuid": "139adceff406467eb3ed8a9db9dd1d1a" } }' https://(URL: base_env_url)/v5/server/token/user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "app_uuid": "139adceff406467eb3ed8a9db9dd1d1a",
        "created": "2015-08-20T22:42:25",
        "expires": "2015-08-27T22:42:25",
        "is_valid": true,
        "user_uuid": "d6a1b136066e41c2ad430e28b5f00524"
    }
}
JSON Parameters:

  • app_uuid (str) – The app UUID that the token is associated with

  • created (str) – The time, in UTC, at which the token was created

  • expires (str) – The time, in UTC, at which the token expires

  • is_valid (boolean) – Indicates if the token was valid when it was queried.

  • user_uuid (str) – The Rave ID that the token is associated with

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 402: Application does not exist. An api_key that does not exist was specified.

  • 433: The token was not valid. This may happen for a number of reasons: the token has expired, the token is not associated with the specified application, or decryption of the token failed.

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Get all Rave IDs identities from a token#

POST /v5/server/token/user/identities#

For valid tokens, returns the primary Rave ID, app, and all the merged Rave IDs for the user that the token is associated with, as well as expiration and creation times for the token.

POST /v5/server/token/user/identities HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "token": "AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc",
    "app": {
        "uuid": "139adceff406467eb3ed8a9db9dd1d1a"
    }
}

Making a request with curl:

curl -X POST -H 'Content-Type: application/json' -d '{ "token": "AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc", "app": { "uuid": "139adceff406467eb3ed8a9db9dd1d1a" } }' https://(URL: base_env_url)/v5/server/token/user/identities

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "app_uuid": "139adceff406467eb3ed8a9db9dd1d1a",
        "created": "2015-08-20T22:42:25",
        "expires": "2015-08-27T22:42:25",
        "is_valid": true,
        "merged_identities": [
            "cd42d929d16a4331b1196062fbd27e08",
            "1a2fe3279ed5464590671527761d65f9"
        ],
        "user_uuid": "d6a1b136066e41c2ad430e28b5f00524"
    }
}
JSON Parameters:

  • app_uuid (str) – The app UUID that the token is associated with

  • created (str) – The time, in UTC, at which the token was created

  • expires (str) – The time, in UTC, at which the token expires

  • is_valid (boolean) – Indicates if the token was valid when it was queried.

  • merged_identities (list) – A list of Rave IDs that have been merged into the user the token is associated with

  • user_uuid (str) – The Rave ID that the token is associated with

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 402: Application does not exist. An api_key that does not exist was specified.

  • 433: The token was not valid. This may happen for a number of reasons: the token has expired, the token is not associated with the specified application, or decryption of the token failed.

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Get extended user info from a token#

POST /v5/server/token/user/info#

For valid tokens, returns information about the user that the token is associated with, as well as expiration and creation times for the token.

POST /v5/server/token/user/info HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json

{
    "token": "AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc",
    "app": {
        "uuid": "139adceff406467eb3ed8a9db9dd1d1a"
    }
}

Making a request with curl:

curl -X POST -H 'Content-Type: application/json' -d '{ "token": "AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc", "app": { "uuid": "139adceff406467eb3ed8a9db9dd1d1a" } }' https://(URL: base_env_url)/v5/server/token/user/info

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "app_uuid": "139adceff406467eb3ed8a9db9dd1d1a",
        "created": "2015-08-20T22:42:25",
        "expires": "2015-08-27T22:42:25",
        "is_valid": true,
        "user": {
            "display_name": "Test User",
            "email": "test.user@example.com",

            "hmid": "oegcydf2p0ypkkgewpyv4yfe0ft1v1p45fan7xxn52e8qjos7dfhk34nxh7ijdsm",

            "profile_image_url": null,
            "state": "authenticated",
            "username": "testuser1",
            "uuid": "d6a1b136066e41c2ad430e28b5f00524"
        },
        "app_save_keys": {
            "selected": "290f43323b6f74fc93109ef6eef45f21",
            "rejected": [],
            "unresolved": []
        }
    }
}
JSON Parameters:

  • app_uuid (str) – The app UUID that the token is associated with

  • created (str) – The time, in UTC, at which the token was created

  • expires (str) – The time, in UTC, at which the token expires

  • is_valid (boolean) – Indicates if the token was valid when it was queried.

  • user[display_name] (str) – Rave account’s display name

  • user[email] (str) – Rave account’s email

  • user[hmid] (str) – Rave account’s Big Fish hMID

  • user[profile_image_url] (str) – Rave account’s profile image URL

  • user[state] (str) – Rave account’s state

  • user[username] (str) – Rave account’s username

  • user[uuid] (str) – Rave account’s ID

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 402: Application does not exist. An api_key that does not exist was specified.

  • 433: The token was not valid. This may happen for a number of reasons: the token has expired, the token is not associated with the specified application, or decryption of the token failed.

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Server Side Gifting#

For the overview of the gifting system, please refer to the Gifting and Requests section of documentation under iOS, Android or Unity SDK documentation. This documentation section only describes how to leverage the gifting and requests APIs from your server.

Get Pending Gifts for App#

GET /v5/application/:app_uuid/gifts#

Get a list of gifts and gift requests that are available for an application

Example request:

GET /v5/application/0123456789abcdef0123456789abcdef/gifts HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X GET \
  https://(URL: base_env_url)/v5/applications/0123456789abcdef0123456789abcdef/gifts \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "can_gift": true,
            "can_request": true,
            "created_at": "2013-03-21T18:00:00",
            "key": "life",
            "name": "Life",
            "uuid": "28812245aa474d28bc5d4134a008659e"
        },
        {
            "can_gift": false,
            "can_request": true,
            "created_at": "2013-03-21T18:00:00",
            "key": "power",
            "name": "Power-up",
            "uuid": "1248ace8259a432a8d9902bf9a92fff5"
        },
        {
            "can_gift": true,
            "can_request": false,
            "created_at": "2013-03-21T18:00:00",
            "key": "extra",
            "name": "Extra time",
            "uuid": "af00ea18ee0046b1a1263f5c31219c73"
        }
    ]
}
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 402: Application does not exist. An api_key that does not exist was specified.

  • 700: A validation error occurred. See the error message for the offending argument.

Get Pending Gifts for Current User for App#

GET /v5/me/gifts#

Get a list of pending gifts for the current user

Example request:

GET /v5/me/gifts HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X GET \
  https://(URL: base_env_url)/v5/me/gifts \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "gifts": [
            {
                "time_sent": "2019-08-22T13:23:02",
                "source": "gift",
                "type": "1248ace8259a432a8d9902bf9a92fff5",
                "gift_key": "powe1",
                "user": "0d92da7d91e611e29d8b14109fd57781",
                "uuid": "bae6a7c9642e4b6b9c58ee5f754f4e1d"
            }
        ]
    }
}
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

Send Gift#

POST /v5/me/gifts#

Send a gift to one or more Rave users

Example request:

POST /v5/me/gifts HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X POST \
  https://(URL: base_env_url)/v5/me/gifts \
  -H 'Content-Type: application/json' \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc' \
  -d '{
    "gift": {
        "key": "power",
        "users": [
            "5bfc7a6b91f511e2a3e714109fd57781",
            "777b1d1491f511e296a214109fd57781"
        ]
    }'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "failed": [],
        "succeeded": [
            "5bfc7a6b91f511e2a3e714109fd57781",
            "777b1d1491f511e296a214109fd57781"
        ]
    }
}
JSON Parameters:

  • key (str) – The gift type key

  • users (array[str]) – The list of users UUIDs that the gift will be sent to

Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Accept Gift#

PUT /v5/me/gifts/:gift_uuid#

Acknowledge a gift for the current user

Example request:

PUT /v5/me/gifts/e2081c449021484fb1bcaf82feb755a7 HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X PUT \
  https://(URL: base_env_url)/v5/me/gifts/e2081c449021484fb1bcaf82feb755a7 \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "time_sent": "2019-08-22T13:26:53",
        "source": "gift",
        "type": "1248ace8259a432a8d9902bf9a92fff5",
        "gift_key": "power",
        "user": "0d92da7d91e611e29d8b14109fd57781",
        "uuid": "e2081c449021484fb1bcaf82feb755a7"
    }
}
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 413: Gift does not exist. A gift_uuid that does not exist was specified.

  • 700: A validation error occurred. See the error message for the offending argument.

Get Gift Count#

GET /v5/me/gifts/count#

Get a count of pending gifts for the current user

Example request:

GET /v5/me/gifts/count HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X GET \
  https://(URL: base_env_url)/v5/me/gifts/count \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "count": 2
    }
}
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

Get Pending Requests#

GET /v5/me/requests#

Get a list of pending requests for the current user

Example request:

GET /v5/me/requests HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X GET \
  https://(URL: base_env_url)/v5/me/requests \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "requests": [
            {
                "time_sent": "2019-08-23T03:19:50",
                "type": "1248ace8259a432a8d9902bf9a92fff5",
                "gift_key": "power",
                "user": "0d92da7d91e611e29d8b14109fd57781",
                "uuid": "03fad1be803b498588fc0c49b9067aa8"
            }
        ]
    }
}
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

Send Request for a Gift#

POST /v5/me/requests#

Send a request to one or more Rave users

Example request:

POST /v5/me/requests HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X POST \
  https://(URL: base_env_url)/v5/me/requests \
  -H 'Content-Type: application/json' \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc' \
  -d '{
    "request": {
        "key": "power",
        "users": [
            "5bfc7a6b91f511e2a3e714109fd57781",
            "777b1d1491f511e296a214109fd57781"
        ]
    }'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "failed": [],
        "succeeded": [
            "5bfc7a6b91f511e2a3e714109fd57781",
            "777b1d1491f511e296a214109fd57781"
        ]
    }
}
JSON Parameters:

  • key (str) – The gift type key

  • users (array[str]) – The list of users UUIDs that the gift request will be sent to

Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Grant Received Request#

PUT /v5/me/requests/:request_uuid#

Grant a request the current user received

Example request:

PUT /v5/me/requests/03fad1be803b498588fc0c49b9067aa8 HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X PUT \
  https://(URL: base_env_url)/v5/me/requests/03fad1be803b498588fc0c49b9067aa8 \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "time_sent": "2019-08-23T03:19:50",
        "type": "1248ace8259a432a8d9902bf9a92fff5",
        "gift_key": "power",
        "user": "0d92da7d91e611e29d8b14109fd57781",
        "uuid": "03fad1be803b498588fc0c49b9067aa8"
    }
}
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 413: Request does not exist. A request_uuid that does not exist was specified.

  • 700: A validation error occurred. See the error message for the offending argument.

Reject Request#

DELETE /v5/me/requests/:request_uuid#

Reject a request the current user received

Example request:

DELETE /v5/me/requests/03fad1be803b498588fc0c49b9067aa8 HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X DELETE \
  https://(URL: base_env_url)/v5/me/requests/03fad1be803b498588fc0c49b9067aa8 \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 413: Request does not exist. A request_uuid that does not exist was specified.

  • 700: A validation error occurred. See the error message for the offending argument.

Get Request Count#

GET /v5/me/requests/count#

Get a count of pending requests for the current user

Example request:

GET /v5/me/requests/count HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X GET \
  https://(URL: base_env_url)/v5/me/requests/count \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "count": 2
    }
}
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

Send Gift to User Not Yet Playing#

POST /v5/me/gifts/external#

Send a gift to one or more recipients who are not Rave users. Gifts are associated with the social network UIDs that are provided and are applied to Rave user accounts when those social network UIDs are associated with a Rave account.

Example request:

POST /v5/me/gifts/external HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X POST \
  https://(URL: base_env_url)/v5/me/gifts/external \
  -H 'Content-Type: application/json' \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc' \
  -d '{
    "external_gift": {
        "key": "power",
        "google_uids": [
            "100000000000000000006"
        ]
    }'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "facebook_uids": [],
        "gplus_uids": [],
        "google_uids": [
            "100000000000000000006"
        ]
    }
}
JSON Parameters:

  • key (str) – The gift type key

  • google_uids (array[str]) – The list of user google UUIDs that the gift will be sent to

Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Register External Gift#

POST /v5/me/gifts/contents#

Register contents for a pending gift identified by a reference value. Store information about a gift sent to a non-Rave user. The gift information is identified by an external source (e.g. ‘facebook’) and a reference value

Example request:

POST /v5/me/gifts/external HTTP/1.1
Host: (URL: base_env_url)
Content-Type: application/json
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X POST \
  https://(URL: base_env_url)/v5/me/gifts/external \
  -H 'Content-Type: application/json' \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc' \
  -d '{
    "gift_content": {
            "key": "power",
            "num": 1,
            "source": "facebook",
            "ref": "foo"
        }
    }'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "ref": "foo",
        "source": "facebook",
        "gift_key": "power",
        "num": 1
    }
}
JSON Parameters:

  • key (str) – The gift type key

  • num (int) – The number of users the gift is sent to

  • source (str) – The gift source

  • source – The gift reference

Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

  • 760: One or more required arguments were missing

Get External Gift Info#

GET /v5/gifts/contents#

Get information about a pending gift

Example request:

GET /v5/gifts/contents HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X GET \
  https://(URL: base_env_url)/v5/gifts/contents?source=facebook&ref=foo \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "ref": "foo",
        "source": "facebook",
        "gift_key": "powe1",
        "num": 1
    }
}
Query Parameters:

  • source – The gift source

  • ref – The gift reference

Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

Delete Gift#

DELETE /v5/gifts/contents#

Mark information about a pending gift as having been fetched by one of the gift recipients. This will decrement the ‘num’ value by one for the gift content instance. Once the ‘num’ value has reached 0, the instance will be deleted.

Example request:

DELETE /v5/me/gifts/contents HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X DELETE \
  https://(URL: base_env_url)/v5/me/gifts/contents \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 700: A validation error occurred. See the error message for the offending argument.

Server Side Friends and Followers#

For the overview of the Friends and Followers system, please refer to the Friends and Followers section of documentation under iOS, Android or Unity SDK documentation. This documentation section only describes how to leverage the friends and followers APIs from your server.

Get User’s Friends List#

GET /v5/me/friends/(str: list_name)/contacts#

Get a user’s friends from the given list

  • global._friend: A list of friends available in all apps

  • app._friend: A list of friends available only in the current app. Each app has such a list automatically created for it.

Example request:

GET /v5/me/friends/app.friends/contacts HTTP/1.1
Host: (URL: base_env_url)
Rave-App-UUID: 0123456789abcdef0123456789abcdef
Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc

Making a request with curl:

curl -X GET \
  https://(URL: base_env_url)/v5/me/friends/app.friends/contacts \
  -H 'Rave-App-UUID: 0123456789abcdef0123456789abcdef' \
  -H 'Rave-User-Token: AROa3O_0BkZ-s-2KnbndHRpV35JRhU-1F0v3T-LcEOLRXkmQwVfSKQyhrgREntgF3Rb6GNUItWBA0y52SNbihOTKNhRvg3goDW3t9s.1vp35ytjRTLnrU1IXECd5pGxPQc'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json


{
    "data": {
        "users": [
            {
                "uuid": "5bfc7a6b91f511e2a3e714109fd57781",
                "display_name": "Facebook User",
                "name": "User",
                "profile_image_url": "http://graph.facebook.com/123/picture",
                "username": "fb_user1"
            }
        ]
    }
}
Request Headers:

  • Rave-App-UUID – The app UUID that the token is associated with

  • Rave-User-Token – The user auth token

Status Codes:

  • 200 OK – The request was processed without problems

Errors

  • 1002: List does not exist. A list_name that does not exist was specified.

  • 1008: Invalid system list name. A list_name that is invalid was specified.

  • 700: A validation error occurred. See the error message for the offending argument.

Contents