Skip to main content

Authentication 🔐

Authentication guide 📘​

To ensure secure and standardized access to Straumann® AXS APIs, authentication is handled via Azure AD B2C.

All integrations must use the OAuth 2.0 Client Credentials Flow, which is designed for server-to-server communication without user interaction.

Flow Steps (Client Credentials Flow) 🔄​

  1. Authenticate with Azure AD B2C token endpoint providing:
  • client_id
  • client_secret
  • scope

  1. AXS validates the credentials and issues an access token.

  2. Use this access token in the Authorization: Bearer <token> header when calling our APIs.

Token validation 🧾​

1. Token Endpoint (Azure AD B2C) 🌐​

Environment

  • Preproduction/Staging:

https://stgoneportalppr.b2clogin.com/stgoneportalppr.onmicrosoft.com/b2c_1a_partnerIntegration_v1/oauth2/v2.0/token

  • Production

https://stgoneportalprd.b2clogin.com/stgoneportalprd.onmicrosoft.com/b2c_1a_partnerIntegration_v1/oauth2/v2.0/token

2. Request parameters 🧩​

ParameterValue
grant_typeclient_credentials
client_idProvided during your onboarding
client_secretProvided during your onboarding

3. Sample Token Request/Response (cURL) 💻​

 curl -X POST https://stgoneportalppr.b2clogin.com/stgoneportalppr.onmicrosoft.com/b2c_1a_partnerIntegration_v1/oauth2/v2.0/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"

Response JSON:

{
  "token_type": "Bearer",
  "expires_in": 1800,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn..."  
}

4. Using Access Token 🔧​

Include the access token in the Authorization header of each API call:

GET /orders HTTP/1.1
Host: api.axs.straumann.com
Authorization: Bearer eyJ0eXAiOiJKV1Qi...

Common Errors ⚠️​

HTTP StatusMeaningResolution Tip
401Unauthorized / Invalid tokenEnsure token is valid and correctly set in header
403ForbiddenCheck scope, roles, or API permissions
400Bad requestCheck formatting and parameter names in token call

Access Token Overview 🧠​

Once successfully authenticated via the Client Credentials flow, your application will receive an OAuth 2.0 access token.

This token is a JWT (JSON Web Token) — a compact, self-contained token that includes information about the client, its permissions, and the token validity window.

How to use the Token 🧪​

Include the access token in the Authorization header of every API request:

GET /api/resource HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...

Tokens are valid for 1800 seconds. After expiry, the app must request a new one using the same client credentials.

Sample Decoded JWT Payload 🔍​

Below is an example decoded access token returned by Azure AD B2C for a client credentials request:

{
  "aud": "9a942c36-2d72-4e5f-bb86-c1a460b21484",
  "iss": "https://stgoneportaldev.b2clogin.com/15ffdd0b-d70d-43b9-ac10-56bc20deb9e3/v2.0/",
  "exp": 1753187433,
  "nbf": 1753185633,
  "tid": "15ffdd0b-d70d-43b9-ac10-56bc20deb9e3",
  "scp": "User.Read.All File.Read Organization.Read.All Patient.Read Patient.Write",
  "ipaddr": "192.168.1.1",
  "azpacr": "1",
  "sub": "6ab0ba22-a3b1-4d9c-82ae-15e5ab8549c8",
  "oid": "6ab0ba22-a3b1-4d9c-82ae-15e5ab8549c8",
  "ver": "2.0",
  "azp": "69bfd158-bd1a-4f43-bcb0-881365d779d5",
  "iat": 1753185633
}

Fields explained 🏷️​

ParameterValue
audAudience — identifies the API this token is intended for. This must match the client_id issued to the requesting service/application.
issIssuer — Azure AD B2C URL that issued the token.
expExpiration — timestamp when the token expires.
nbfNot Before — token is not valid before this time.
iatIssued At — time the token was issued.
tidTenant ID — Azure AD B2C directory ID.
scpScopes — permissions granted to this token. These correspond to what the client app is allowed to access.
azpAuthorized party (client ID of the app making the request).
sub/oidSubject/Object ID — unique identifier for the client identity (same in client credentials flow).
verToken version. Should be 2.0.

Token Validation ✅​

Your backend services should validate incoming tokens by:

  • Verifying the signature using Azure AD public keys
  • Ensuring the aud (audience) matches your API
  • Validating scp (scopes) if implementing fine-grained authorization

Onboarding Checklist ✅​

✅ Receive your client_id and client_secret from our team
✅ Successfully generate an access token
✅ Call API with Authorization: Bearer <token> header
✅ Handle token expiration (tokens are valid for 1800s by default)