ContactsLog inGet startedAsk Navixy AI

Authentication

Authentication is required for all API requests and is based on OAuth 2.0.

Authentication environments

Base URLs

Region
Base URL
Data Location

Europe

https://keycloak.navixy.com

European data centers

Americas

https://keycloak.us.navixy.com

US-based data centers

Note that in this and other articles about Navixy Repository API, {AUTH_BASE_URL} is a placeholder for the URL you'll be using.

Organization-based access control

All API requests are automatically scoped to your organization. Your access token determines the organization context. You cannot access resources belonging to other organizations.

How organization scoping works

  1. When you authenticate, your access token contains your organization identifier.

  2. The API automatically extracts this identifier from your token.

  3. All operations are restricted to your organization's resources.

  4. No manual organization specification is required in API calls.

OAuth 2.0 scopes

Navixy Repository API uses standard OpenID Connect scopes for authentication and authorization. When requesting an access token, you can specify one or more of the following scopes:

Scope
Description

openid

Required for OpenID Connect authentication. This scope enables the authentication flow and allows the API to verify your identity. Include this scope in all authentication requests.

profile

Access to basic user profile information. Grants access to standard profile claims such as name, preferred username, and other non-sensitive profile data associated with your account.

email

Access to user email address. Provides access to the user's verified email address. This scope is useful for account identification and communication purposes.

Example authorization request:

curl -L \
  --request GET \
  --url "{AUTH_BASE_URL}/realms/users/protocol/openid-connect/auth" \
  --data-urlencode 'scope=openid profile email'

Important notes:

  • The openid scope is mandatory for all authentication flows

  • Multiple scopes should be separated by spaces when passed as URL parameters

  • All API operations are automatically scoped to your organization — no additional API-specific scopes are required

  • Requested scopes will be included in the access token and determine what user information is available through the token introspection

Acquiring an access token

Navixy Repository API supports the OAuth2 Authorization Code Flow.

Prerequisites

Before you begin, ensure you have:

  • Valid Navixy Repository API credentials (client_id and client_secret).

  • A registered Callback URL (Redirect URI): The specific URL in your application where users will be redirected after granting consent.

  • Authentication server URL ({AUTH_BASE_URL}), determined depending on your geographical location. For information about {AUTH_BASE_URL}, see Authentication environments.

  • A secure method to generate and validate the state parameter for Cross-Site Request Forgery (CSRF) protection.

1

Redirect the user to the authorization endpoint:

curl -L \
  --request GET \
  --url "{AUTH_BASE_URL}/realms/users/protocol/openid-connect/auth" \
  --data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
  --data-urlencode 'response_type=code' \
  --data-urlencode 'redirect_uri=https://<YOUR_APP_CALLBACK_URL>' \
  --data-urlencode 'scope=<REQUESTED_SCOPE_ONE> <REQUESTED_SCOPE_TWO>' \
  --data-urlencode 'state=<YOUR_SECURE_RANDOM>'
2

Exchange authorization code for access token

Request:

curl -L \
  --request POST \
  --url '{AUTH_BASE_URL}/realms/users/protocol/openid-connect/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "authorization_code",
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "code": "<YOUR_AUTHORIZATION_CODE>",
    "redirect_uri": "https://<YOUR_APP_CALLBACK_URL>"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...signature",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8",
  "scope": "<REQUESTED_SCOPE_ONE> <REQUESTED_SCOPE_TWO>",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.e...signature"
}

Error example:

{
  "error": "invalid_grant",
  "error_description": "Authorization code expired"
}

Transmitting the access token

Use access_token to authenticate API requests:

curl -L \
  --request GET \
  --url '{BASE_URL}/resource' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Refreshing the access token

Access tokens have a limited lifespan and typically expire after 900 seconds. To maintain access without requiring the user to re-authenticate, use the refresh token provided during the initial token exchange to obtain a new access token.

Request:

curl -L \
  --request POST \
  --url '{AUTH_BASE_URL}/realms/users/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>' \
  --data 'refresh_token=<YOUR_REFRESH_TOKEN>'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...signature",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8",
  "scope": "<REQUESTED_SCOPE_ONE> <REQUESTED_SCOPE_TWO>"
}

Notes:

  • The new access_token should replace the old one in all subsequent API requests.

  • A new refresh_token may also be issued. If so, you should update your stored token accordingly.

  • If the refresh_token has expired or is invalid, you must re-authenticate using the full authorization code flow.

This mechanism enables long-lived sessions while minimizing user effort and adhering to security best practices.

Revoking tokens

If an access token or refresh token needs to be invalidated (for example, when a user logs out or client credentials are rotated), it can be revoked using the OAuth2 token revocation endpoint:

curl -L \
  --request POST \
  --url '{AUTH_BASE_URL}/realms/users/protocol/openid-connect/revoke' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "token": "<TOKEN_TO_REVOKE>"
  }'

Revoked tokens become immediately invalid and cannot be used for accessing protected resources.

Security recommendations

  • Always send tokens over HTTPS. Any requests made over plain HTTP will be rejected.

  • Never expose client secrets or tokens in frontend code or public repositories.

  • Access tokens are short-lived and should be refreshed or re-requested as needed.

Using a third-party library

To simplify integration, we recommend using ready-made OAuth 2.0 client libraries:

For browser-based applications

Universal

  • oidc-client-ts – A popular and well-maintained library for managing OAuth2 and OIDC tokens in browser apps.

  • AppAuth-JS – Official OpenID Connect client library for JavaScript.

For React

  • react-oidc-context – Wrapper around the oidc-client-ts, OIDC/OAuth2 support with React Context API, highly recommended for larger apps.

  • react-oauth2-code-pkce – Lightweight React hook for OAuth2 Authorization Code Flow.

For Vue.js

  • vuex-oidc – Wrapper around the oidc-client-ts, integration of OIDC authentication with Vuex.

For Angular

For mobile applications

For server-side applications

For Java

For Kotlin

For Python

  • Authlib – Universal OAuth2 and OpenID Connect client for Python.

  • requests-oauthlib – Provides OAuth library support for Requests.

For Node.js

  • openid-client – OAuth 2 / OpenID Connect Client API for JavaScript Runtimes.

  • Simple OAuth2 – A simple Node.js client library for OAuth2.

For Go

For ASP.NET Core

For PHP

PreviousGetting startedNextTechnical reference

Last updated

Was this helpful?