Application API OAuth 2 Authentication

October 15, 2026 at 9:35 AM

OAuth 2 Authentication & Access Process

Step 1: Authentication via World Singles

In order to initiate the authentication process, the client app should POST to our Authorization Server authorize endpoint - /authorize - the following data:

  • client_id (string) [REQUIRED] - the pre-registered UUID that identifies your client app,
  • redirect_uri (string) [REQUIRED] - the pre-registered URI that our OAuth 2 server should redirect to after a user has successfully logged in,
  • response_type (string) [REQUIRED] - the value "code" indicating you are requesting an authorization code,
  • platform (string) [optional] - one of "app_android", "app_ios", or "web"; identifies the host platform for the client application which may be used in logging internally to help us understand behavior across platforms.
  • siteid (numeric) [OPTIONAL] - the ID of the site you want a user to login on; whilst this is optional, it is strongly recommended you supply it if your app knows it!
  • locale (string) [OPTIONAL] - the desired locale in which to display the login page and any error messages. If not supplied, we use the default locale associated with the siteid (above), otherwise we use en_US. The locale must be a valid language_COUNTRY string, e.g., el_GR, en_US, de_DE,
  • state (string) [OPTIONAL] - if present, this value will be passed back to your client app as a URL parameter after a user has successfully logged in; you may want to use this to encode the state of your application prior to authentication so you can restore that state once you regain control.

Your client app must be pre-registered with World Singles, along with the redirect_uri that our OAuth 2 server should redirect to after a successful user login. World Singles will provide you with a client_id (a UUID string that uniquely identifies your client app), and a client_secret (a web-safe base64 string) that is required when requesting an access token. Take care of this information! Whilst we can tell you your client_id, we cannot retrieve your client_secret. We can, however, generate a new client_secret for you.

Note that when you POST to our Authorization Server /authorize endpoint, you will get an HTTP redirect back, that you should honor as if in a web browser. Our login process is a mobile-friendly web application that walks the user through several screens before finally redirecting to your pre-registered redirect_uri at which point your application is back in control, with a code argument (in the query string of the URL) for the next part of the process. If you passed state into the Authorization Server, that will also be passed as a query string argument back into your app.

Step 2: Convert the Authorization Code to an Access/Refresh Token Pair

Once your client app has regained control with the code (and optionally state) query parameter(s) we provided, you need to POST a request to our Authorization Server token endpoint - /token - the following data:

  • client_id (string) [REQUIRED] - the pre-registered UUID that identifies your client app,
  • client_secret (string) [REQUIRED] - the base64 “secret” provided by World Singles when you registered your client app,
  • code (string) [REQUIRED] - the JWT passed back to your client app by our OAuth 2 server, or by the /users POST API when a new member registers,
  • grant_type (string) [REQUIRED] - the value "authorization_code" indicating you are providing an authorization code that World Singles previously supplied you,
  • redirect_uri (string) [REQUIRED] - the pre-registered URI that you provided to our OAuth 2 server (this is used, along with client_id and client_secret, for validation of your request).
  • platform (string) [optional] - one of "app_android", "app_ios", or "web"; identifies the host platform for the client application which may be used in logging internally to help us understand behavior across platforms.

Note that the authorization code is very short-lived - typically just a few seconds - so your app needs to make this request as soon as possible after regaining control, after the user has logged into World Singles.

This POST will return a JSON result, with the following fields:

The access_token JWT you should present as a Bearer token in Authorization headers for all protected requests, the refresh_token JWT you may use with the Authorization Server /token endpoint to request a new access_token when your current one expires, and expires_in which is the number of seconds that the access_token should be valid for (this may help you predict when to use the refresh_token to obtain a new access_token).

{
  "access_token" : "...",
  "refresh_token" : "...",
  "expires_in" : 1800
}

The access_token has a fixed lifetime and when it expires, your API calls will fail with 401 Unauthorized (and a WWW-Authenticate header). When that happens, you should transparently request a new access_token (see below) and retry your failed API call with that new token.

The refresh_token will remain valid while there are active API calls made on behalf of the user associated with these tokens, allowing for a grace period after the access_token expires but before the refresh_token expires.

Step 3A: Accessing the Protected World Singles API

For all API endpoints listed as protected, you must provide an HTTP header called Authorization whose value is the string Bearer followed by a single space followed by your access_token value. Failure to provide a valid token (including an expired token) will result in a 401 Unauthorized response from our API (accompanied by a WWW-Authenticate challenge header).

Step 3B: Accessing the Protected World Singles WebSocket API

Create a secure WebSocket connection to the /ws/updates endpoint on the API server, using wss:// for QA/production, and then send your access_token value as the first text message on that open socket. Thereafter, you will receive messages containing various live updates for the current authenticated member. [Those messages are only documented internally at present]

Step 4: Refreshing your Access Token

When your current access_token expires, you will need to POST to our Authorization Server /token endpoint the following data:

  • client_id (string) [REQUIRED] - the pre-registered UUID that identifies your client app,
  • client_secret (string) [REQUIRED] - the base64 “secret” provided by World Singles when you registered your client app,
  • grant_type (string) [REQUIRED] - the value "refresh_token" indicating your are providing a previously obtained (and valid) refresh_token JWT,
  • refresh_token (string) [REQUIRED] - the JWT previously obtained from this token endpoint.
  • platform (string) [optional] - one of "app_android", "app_ios", or "web"; identifies the host platform for the client application which may be used in logging internally to help us understand behavior across platforms.

This POST will return a JSON result as shown above (a new access_token and refresh_token pair and the expires_in value in seconds).