OAuth 2.0 Authentication

The BlueRound API uses OAuth 2.0 for all authorization. Every request must supply a valid Bearer token in the Authorization header. Tokens are issued by the BlueRound Authorization Server and scoped to exactly the resources your application needs.

GET /v1/users HTTP/1.1
Host: api.blueround.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Quick-Start Flow

        sequenceDiagram
  participant App   as Your Application
  participant Auth  as BlueRound Auth Server
  participant API   as BlueRound API

  App->>Auth: POST /oauth/token (client_id + client_secret)
  Auth-->>App: { access_token, refresh_token, expires_in }
  App->>API:  GET /v1/users  (Authorization: Bearer <access_token>)
  API-->>App: 200 OK — user list
  Note over App,Auth: When access_token expires (3 600 s) …
  App->>Auth: POST /oauth/token (grant_type=refresh_token)
  Auth-->>App: { new access_token, new refresh_token }

Registering Your Application

Before requesting tokens, register your application in the Developer Dashboard to receive:

Credential	Description
`client_id`	Public identifier for your application. Safe to embed in client-side code.
`client_secret`	Private credential used to authenticate your application server-side.

Warning

Your client_secret is private. Never embed it in mobile apps, browser JavaScript, or public repositories. Rotate it immediately if exposed.

Grant Types

BlueRound supports two OAuth 2.0 grant types.

Grant Type	Recommended for
Authorization Code (+ PKCE)	Web apps and mobile apps that act on behalf of an end-user.
Client Credentials	Backend services and machine-to-machine communication (no user context).

Client Credentials Grant

The simplest flow for server-side integrations. Exchange your client_id and client_secret for an access token directly.

Request:

POST /oauth/token — client credentials

curl -X POST "https://auth.blueround.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=users:read users:write"

Response:

{
  "access_token":  "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type":    "Bearer",
  "expires_in":    3600,
  "refresh_token": "def50200a9f3...",
  "scope":         "users:read users:write"
}

Token response fields
Field	Description
`access_token`	JWT to include in every API request.
`token_type`	Always `Bearer`.
`expires_in`	Seconds until the access token expires (3 600 = 1 hour).
`refresh_token`	Long-lived token used to obtain a new access token. Valid for 30 days.
`scope`	Space-separated list of granted scopes.

Authorization Code Grant (+ PKCE)

For user-facing applications. The user is redirected to BlueRound's login page, consents, and is returned to your app with an authorization code that you exchange for tokens.

Important

Always use PKCE (Proof Key for Code Exchange, RFC 7636) with the Authorization Code grant — even for confidential clients — to protect against authorization code interception attacks.

Step 1 — Redirect the user:

https://auth.blueround.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=users:read%20profile:read
  &state=RANDOM_STATE_VALUE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

Step 2 — Exchange the code:

POST /oauth/token — authorization code exchange

curl -X POST "https://auth.blueround.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=CODE_VERIFIER"

Scopes

Request only the scopes your application genuinely needs. Tokens with unnecessary scopes increase the risk if they are compromised.

Scope	Grants access to
`users:read`	List and retrieve user profiles.
`users:write`	Create, update, and deactivate user accounts.
`profile:read`	Read the authenticated user's own profile data.
`profile:write`	Update the authenticated user's own profile data.
`admin`	Full administrative access. Requires explicit approval from BlueRound.

Tip

Combine scopes as a space-separated string in the scope parameter: scope=users:read profile:read.

Refreshing an Access Token

When an access token expires, use the refresh token to obtain a new pair without requiring the user to re-authenticate.

POST /oauth/token — refresh token grant

curl -X POST "https://auth.blueround.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=def50200a9f3..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

The server responds with a new access_token and a rotated refresh_token. Discard the old tokens immediately after a successful refresh — they are single-use.

Warning

Refresh tokens expire after 30 days of inactivity. If a refresh token has expired, the user must re-authenticate from scratch.

Token Expiration Summary

Token Type	TTL	Rotation
Access Token	3 600 s (1 hour)	Issued on every `/oauth/token` call.
Refresh Token	30 days (sliding)	Rotated on every refresh — old token is invalidated.

Revoking a Token

Revoke an access or refresh token immediately — for example, on user log-out or after a security incident.

POST /oauth/revoke

Revoke an active access or refresh token.

Request Headers:

Content-Type -- application/x-www-form-urlencoded

Form Parameters:

token -- The token string to revoke.
token_type_hint -- Optional. access_token or refresh_token.
client_id -- Your application's client_id.
client_secret -- Your application's client_secret.

Status Codes:

200 OK -- Token revoked (or was already invalid). Body is empty.
401 Unauthorized -- Invalid client_id or client_secret.

Revoking a token

curl -X POST "https://auth.blueround.com/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=def50200a9f3..." \
  -d "token_type_hint=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Note

Revoking a refresh token also invalidates all access tokens derived from it.