Skip to main content
API docs by Redocly

Wallboard API - Authentication (2.0)

API Support: [email protected]

Authentication and authorization endpoints for the Wallboard API.

Overview

Wallboard uses OAuth 2.0 for authentication with support for multiple grant types.

Supported Grant Types

Grant Type Use Case Recommended
authorization_code Interactive login (web/mobile apps) Yes
refresh_token Refresh expired access tokens Yes
password Service account API access Legacy only

Authorization Code Flow

The recommended authentication method for all new integrations.

PKCE Flow (Public Clients)

For applications that cannot securely store a client secret (SPAs, mobile apps):

  1. Create OAuth client with "Public" enabled in Wallboard UI
  2. No client_secret required
  3. PKCE (code_challenge/code_verifier) is mandatory

Standard Flow (Confidential Clients)

For server-side applications that can securely store credentials:

  1. Create OAuth client with "Public" disabled in Wallboard UI
  2. client_secret is required
  3. PKCE is optional but recommended

Creating OAuth Clients

You can create your own OAuth clients in the Wallboard UI:

  • Admin level: System Settings > OAuth Clients (system-wide)
  • Customer level: Customer Settings > OAuth Clients (customer-specific)

Configuration options:

Setting Description
redirect_uri Allowed callback URLs (comma-separated)
Public Enable for PKCE-only clients (no secret)
Grant types Select: authorization_code, refresh_token

Password Grant Type (Service Accounts)

Legacy Support Only - Do not use for new integrations.

This grant type exists for backward compatibility with existing M2M (machine-to-machine) integrations.

Requirements:

  1. User must have "Service Account" checkbox enabled in Wallboard UI (User Settings)
  2. Use grant_type=password with user credentials
  3. Token acts on behalf of that user

Regular users cannot use the password grant type unless the "Service Account" option is enabled on their account.

Default client for service accounts:

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

Token Validity

Token Default Extended (kmsi=true)
Access Token 30 minutes 30 minutes
Refresh Token 1 hour 30 days

Token Types

  • access_token: Standard OAuth2 access token (opaque)
  • jwt_access_token: JWT format token for certain API endpoints
  • refresh_token: Long-lived token for obtaining new access tokens

Additional Security Features

  • TOTP: Time-based One-Time Password for 2FA
  • PKCE: Proof Key for Code Exchange (for public clients)
  • SSO: Google, Microsoft, Keycloak, SAML integration

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))

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

OAuth2 token endpoint supporting multiple grant types.

Authorization Code Grant

Exchange authorization code for tokens:

  • Set grant_type=authorization_code
  • Provide code from authorization callback
  • Provide code_verifier if PKCE was used
  • Provide redirect_uri matching the authorization request

Refresh Token Grant

Refresh expired access tokens:

  • Set grant_type=refresh_token
  • Provide refresh_token

Password Grant (Service Accounts Only)

Direct login for service accounts:

  • Set grant_type=password
  • Provide username and password
  • User must have "Service Account" enabled in UI
  • Optionally provide totp for 2FA
header Parameters
Authorization
string
Example: Basic ZGVmYXVsdC1jbGllbnQ6NzYyMTFkYjVkOGVh

Basic authentication with OAuth client credentials. Format: Basic base64(client_id:client_secret)

Required for confidential clients. Not needed for public clients (PKCE).

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 (alternative to Basic auth header)

client_secret
string

Client secret (alternative to Basic auth header)

kmsi
boolean
Default: false

Keep Me Signed In - extends refresh token validity to 30 days

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": "e1c1ae22-61bf-45e8-85a7-65d66a6cdc46",
  • "token_type": "bearer",
  • "expires_in": 1800,
  • "refresh_token": "a5fc1f68-8f7d-43b7-937c-68729b3b4f17",
  • "refresh_total_validity_seconds": 3600,
  • "jwt_access_token": "string",
  • "customerId": 0,
  • "readOnly": false
}

Get JSON Web Key Set

Returns the public keys used to verify JWT tokens. Use this endpoint to validate jwt_access_token values.

Responses

Response samples

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