Skip to main content
API docs by Redocly

Wallboard API - Authentication (2.0)

API Support: [email protected]

Authenticate API requests with an OAuth 2.0 access token issued by your Wallboard server.

Choose a flow

Application Flow Client authentication
Browser app or CLI Authorization code with S256 PKCE Public client ID and code verifier; no secret
Server-side application Authorization code Confidential client ID and secret sent as token-request form fields, or the configured private-key method
Machine-to-machine integration Password Built-in default client and a user explicitly enabled as a Service Account; include TOTP if enabled

For authorization-code flows, configure a client with the integration's callback URI and required grant types. Public clients cannot keep a secret; use PKCE.

Authorize and call the API

  1. For authorization-code flows, send the user to GET /oauth/authorize with your client_id, redirect_uri, response_type=code, scope=FULL_ACCESS and a random state. Public clients must also send code_challenge=BASE64URL(SHA256(code_verifier)).
  2. Check the returned state, then exchange the callback's code at POST /oauth/token using application/x-www-form-urlencoded. Send the same redirect URI and client ID, plus the PKCE verifier or confidential client credentials as appropriate.
  3. Send Authorization: Bearer <access_token> with subsequent API requests.

The authorization-code exchange does not read HTTP Basic credentials. For a client using a secret, send client_id and client_secret in the form body. Password and refresh grants also accept Basic authentication. Keep confidential integration secrets in server-side applications.

Password grant for service accounts

Enable Service Account in the user's settings, then use the built-in client:

Property Value
client_id default-client
client_secret 76211db5d8ea
Basic Auth Basic ZGVmYXVsdC1jbGllbnQ6NzYyMTFkYjVkOGVh

This client supports password and refresh grants. Send grant_type=password, the service account's username and password, and totp when 2FA is enabled. Authenticate the client with the Basic header above or the two client form fields. The shared client credentials do not replace user authentication.

Refresh and token lifetimes

Token Omitted kmsi or kmsi=true kmsi=false
Access token 30 minutes 30 minutes
Refresh token 30 days 1 hour

Send kmsi on the token request. It is evaluated on code exchange and every refresh, so repeat kmsi=false when the one-hour lifetime is required.

To renew a session, send grant_type=refresh_token, the current refresh_token and client authentication to /oauth/token. Each successful refresh consumes the old refresh token. Persist the replacement and serialize refresh attempts for that session. HTTP 400 with error=invalid_grant can indicate an expired, invalid or already-consumed refresh token; start a new authorization flow when renewal fails. API requests with an expired access token return 401; insufficient permissions return 403.

OAuth discovery

OAuth-capable clients can inspect /.well-known/oauth-authorization-server for server capabilities and /.well-known/oauth-protected-resource/mcp for the MCP resource. Registration, HTTPS Client ID Metadata Documents and private-key authentication depend on server policy and version. When resource is supplied during authorization and code exchange, its values must match.

authorization

OAuth2 authorization flow

Start Authorization Code flow

Initiates the OAuth2 Authorization Code flow. Redirects user to login page, then back to redirect_uri with authorization code.

For Public Clients (PKCE): Include code_challenge parameter - this is mandatory for public clients.

For Confidential Clients: code_challenge is optional but recommended.

query Parameters
client_id
required
string

Your OAuth client ID (created in Wallboard UI)

redirect_uri
required
string <uri>

URI to redirect after authorization (must be registered)

response_type
required
string
Value: "code"

Must be "code" for authorization code flow

scope
required
string

Access scope. Use FULL_ACCESS for general API access.

state
required
string

Random state value for CSRF protection (min 3 chars, returned in callback)

code_challenge
string

PKCE code challenge (S256 method only). Required for public clients, recommended for all. Generate: BASE64URL(SHA256(code_verifier))

resource
string <uri>

Optional OAuth resource binding.

Responses

Request samples 

# Step 1: Generate PKCE verifier and challenge
# The verifier is a random string, challenge is its SHA256 hash
code_verifier="YOUR_RANDOM_43_TO_128_CHAR_STRING"
# In bash: code_verifier=$(openssl rand -base64 32 | tr -d '=/+')

# Generate challenge (S256 method)
# code_challenge = BASE64URL(SHA256(code_verifier))

# Step 2: Redirect user to authorization URL
https://{server}/oauth/authorize?\
  client_id=YOUR_CLIENT_ID&\
  redirect_uri=https://your-app.com/callback&\
  response_type=code&\
  scope=FULL_ACCESS&\
  state=random_csrf_state&\
  code_challenge=YOUR_CODE_CHALLENGE&\
  code_challenge_method=S256

# Step 3: User logs in, gets redirected to:
# https://your-app.com/callback?code=AUTH_CODE&state=random_csrf_state

# Step 4: Exchange code for token
curl -X POST 'https://{server}/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=AUTH_CODE' \
  -d 'code_verifier=YOUR_RANDOM_43_TO_128_CHAR_STRING' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'redirect_uri=https://your-app.com/callback'

token

OAuth2 token operations

Get or refresh access token

Exchange an authorization code, refresh a session, or authenticate an enabled service account. Each successful refresh consumes the old refresh token and returns a replacement; serialize refresh attempts and persist the replacement. kmsi applies to each token request and defaults to true (30 days); false gives one hour. Clients must handle HTTP 400 invalid_grant for expired or already-consumed refresh tokens.

header Parameters
Authorization
string
Example: Basic <base64-client-id-and-secret>

Client Basic authentication where supported. Confidential code exchange should send client_id and client_secret as form fields; public PKCE clients do not send a secret.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Enum: "authorization_code" "refresh_token" "password"

OAuth2 grant type

code
string

Authorization code (for authorization_code grant)

code_verifier
string

PKCE code verifier (for authorization_code grant with PKCE)

redirect_uri
string <uri>

Redirect URI (must match authorization request)

refresh_token
string

Refresh token (for refresh_token grant)

username
string <email>

Service account email (for password grant)

password
string <password>

Service account password (for password grant)

totp
string

TOTP code for 2FA (if enabled on service account)

client_id
string

Client ID. Send as a form field for authorization-code exchange; password and refresh grants also accept Basic authentication.

client_secret
string

Confidential client secret. Send as a form field for authorization-code exchange; omit for public PKCE clients. Password and refresh grants also accept Basic authentication.

kmsi
boolean
Default: true

Refresh-token lifetime: true or omitted = 30 days; false = one hour. Evaluated on code exchange and every refresh.

resource
string <uri>

OAuth resource binding; must agree with the authorization request when supplied.

client_assertion_type
string

Client assertion type for a client configured for private_key_jwt.

client_assertion
string

Signed client assertion for private_key_jwt authentication.

Responses

Request samples 

curl -X POST 'https://{server}/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=AUTH_CODE_FROM_CALLBACK' \
  -d 'code_verifier=YOUR_CODE_VERIFIER' \
  -d 'client_id=your-client-id' \
  -d 'redirect_uri=https://your-app.com/callback'

Response samples

Content type
application/json
{
  • "access_token": "<access-token>",
  • "token_type": "bearer",
  • "expires_in": 1800,
  • "refresh_token": "a5fc1f68-8f7d-43b7-937c-68729b3b4f17",
  • "refresh_total_validity_seconds": 2592000,
  • "customerId": 0,
  • "readOnly": false
}

Get JSON Web Key Set

Returns the public keys used to verify JWT tokens. Use these keys to verify access_token signatures.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}