Skip to main content

Getting started

This guide takes you from no credentials to a successful Breeze API call.

Prerequisites​

  • A client_id and client_secret from a Breeze administrator. See OAuth Client Management for how administrators create clients.
  • The Authentication guide covers the token flow in depth — caching, expiry, and error codes.

Environments​

EnvironmentBase URL
Testhttps://system.upnxt.no
Productionhttps://system.idportal.no

Both environments serve the same two endpoints: POST /oauth/token and POST /graphql. Credentials are environment-specific — a test client_id does not work in production. Build and verify your integration against the test environment first; your Breeze administrator provides test credentials.

All code samples in these docs use the test environment.

Step 1: Request an access token​

curl -X POST https://system.upnxt.no/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "oauth_abc123",
    "client_secret": "s3cr3t_xyz789"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Tokens are valid for 1 hour. Cache the token and reuse it — requesting a new token on every call will hit rate limits.

Step 2: Make your first API call​

The GraphQL endpoint is /graphql.

curl -X POST https://system.upnxt.no/graphql \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"query": "query GetCurrentUser { Me { _id userId email } }"}'

Response:

{
  "data": {
    "Me": {
      "_id": "user_abc123",
      "userId": "integration@example.com",
      "email": "integration@example.com"
    }
  }
}

Me returns the identity of the authenticated client. A successful response confirms your token is valid and the API is reachable. See the Me reference for all available fields.

Step 3: Handle errors​

The API returns errors in different formats depending on where the failure occurs. GraphQL errors appear in the errors array:

{
  "errors": [{ "message": "Credential not found", "extensions": { "code": "NOT_FOUND" } }],
  "data": null
}

Token endpoint errors use the OAuth 2.0 format:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

See Error handling for all error codes and Rate limiting for 429 handling.

Next steps​