Viana Connect API

Appearance

Authentication ​

This API uses OAuth2 Client Credentials for business-to-business access.

API Endpoints ​

API Base URLhttps://prod-gcp.services.api.viana.ai
Token Endpointhttps://prod-gcp.id2.viana.ai/auth/realms/production/protocol/openid-connect/token

Keep credentials secure

Treat your client_secret like a password. Do not embed it in client-side apps or expose it in logs.

OAuth2 Client Credentials Flow ​

Partners authenticate using the OAuth2 Client Credentials grant type (M2M, no user login). You will be issued a client_id and client_secret to exchange for short-lived access tokens.

Portal access coming soon

Soon you will be able to access and manage these credentials directly in the Viana partner portal.

Step 1: Get an access token ​

Use the Token Endpoint from the API Endpoints table above.

http
POST <TOKEN_ENDPOINT>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Response:

json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Step 2: Use the token in API requests ​

Include the token in every API request as a Bearer token in the Authorization header:

http
GET /api/v1/devices/status
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Token expiry and refresh ​

  • Tokens expire after the period shown in expires_in (seconds). Request a new token before it expires.
  • There is no refresh token in client credentials flow. Re-request a token using your credentials.
  • Recommended: cache the token and re-request when it has less than 30 seconds remaining.

Operational recommendation

Use centralized token management in your integration service so all API calls share one valid cached token.

Network access scoping ​

Your token contains a network_ids claim configured by Viana during onboarding. The first network in the claim is used by default — no header needed for single-network tokens.

For multi-network tokens, pass X-Network-Name to explicitly target a network:

http
X-Network-Name: Acme Retail

The name must match a network authorised by your token, otherwise the request is rejected with 401.

Legacy API key ​

If you were issued a viana_sk_* API key instead of client credentials, pass it via:

http
X-API-Key: viana_sk_xxxxxxxxxxxx

Or as a Bearer token:

http
Authorization: Bearer viana_sk_xxxxxxxxxxxx

A legacy API key is scoped to a single network and signage vendor — no X-Network-Id header is needed. New integrations should use the Keycloak client credentials flow above.