Authentication

Authenticating with the Navexa API

The Navexa API supports two authentication methods:

OAuth 2.0 Authorization Code Flow with PKCE — for applications that act on behalf of a Navexa user.

API Key Authentication — for accessing only your own data with a simpler mechanism.

1. OAuth 2.0 Authorization Code Flow with PKCE

Use OAuth 2.0 when your application needs to act on behalf of a Navexa user and access their data with their consent.

The Navexa OAuth flow requires PKCE (Proof Key for Code Exchange) for all applications, including confidential server-side clients. PKCE protects the authorization code from interception, even if your client_secret is compromised. Most OAuth client libraries (openid-client for Node, Authlib for Python, IdentityModel.OidcClient for .NET, etc.) support PKCE with a single configuration flag.

To request a Client ID and Secret, email help@navexa.com with the subject API Access Request and a brief description of your use case.

Step 1 — Generate PKCE values

Before redirecting the user, generate a PKCE pair on your server:

code_verifier — a cryptographically random string, 43–128 characters from the URL-safe alphabet (A-Z, a-z, 0-9, -, ., _, ~). Store it in the user's session, keyed by state, so you can retrieve it during the token exchange.

code_challenge — BASE64URL(SHA256(code_verifier)). This is sent in the authorize request; the raw verifier never leaves your server until step 3.

Example (Node.js):

Note: use base64url encoding (URL-safe alphabet, no = padding) — not standard Base64.

Step 2 — Redirect the user to the authorization endpoint

https://auth.navexa.io/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  audience=https://api.navexa.io/api&
  scope=openid%20profile%20email%20offline_access&
  state=RANDOM_STRING&
  code_challenge=YOUR_CODE_CHALLENGE&
  code_challenge_method=S256

Parameter	Required	Description
`response_type`	Yes	Must be `code`.
`client_id`	Yes	The Client ID issued to your application.
`redirect_uri`	Yes	Must exactly match a redirect URI registered for your application.
`audience`	Yes	Must be `https://api.navexa.io/api`. This is the Auth0 identifier for the Navexa API — not a URL you call. (The actual API base URL is `https://api.navexa.com.au/api`.) Without this parameter, the access token will not be accepted by the API and calls will return `401 Unauthorized`.
`scope`	Yes	Space-separated list — see Scopes. Must include `offline_access` if you want a refresh token.
`state`	Recommended	A random, unguessable string. Verify it matches when the user is redirected back, to prevent CSRF.
`code_challenge`	Yes	The PKCE challenge from Step 1.
`code_challenge_method`	Yes	Must be `S256`. The plain method is not supported.

After the user signs in and grants consent, Auth0 redirects to your redirect_uri with code and state query parameters.

Step 3 — Exchange the authorization code for tokens

Look up the code_verifier you stored in the user's session in Step 1, then send it alongside the rest of the token request:

curl --request POST \
  --url https://auth.navexa.io/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "YOUR_REDIRECT_URI",
    "code_verifier": "YOUR_CODE_VERIFIER"
  }'

code_verifier must be the original random string from Step 1 — not the hashed challenge. Auth0 hashes the verifier itself and compares it to the stored challenge.

Successful response (HTTP 200):

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "v1.Mr...",
  "id_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "openid profile email offline_access"
}

refresh_token is only returned if offline_access was requested. id_token is only returned if openid was requested.

Step 4 — Call the Navexa API

The Navexa API base URL is https://api.navexa.com.au/api. Send the access token in the Authorization header:

curl --request GET \
  --url https://api.navexa.com.au/api/some-endpoint \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

Refreshing an access token

Access tokens expire — 24 hours for native/server applications, 2 hours for web applications. If you requested offline_access you will have a refresh token — use it to get a new access token without user interaction:

curl --request POST \
  --url https://auth.navexa.io/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

PKCE parameters are not required on the refresh request — they only apply to the initial authorization code exchange.

The response shape matches Step 3. If refresh-token rotation is enabled for your application, the previous refresh token is invalidated and you must store the new one returned in the response.

If the refresh token has been revoked or expired, you'll receive invalid_grant and the user will need to re-authorize via Step 2.

Scopes

The Navexa API does not currently use scoped, per-permission authorization — once a user has authorized your application, the resulting access token can call any endpoint your application is permitted to use. You only need to include standard OpenID Connect scopes:

Scope	Purpose
`openid`	Required for OpenID Connect — returns an `id_token`.
`profile`	Basic profile claims (name, etc.) on the `id_token`.
`email`	Email and email-verified claims on the `id_token`.
`offline_access`	Issues a `refresh_token` so you can refresh access tokens without user interaction.

A typical request will use scope=openid profile email offline_access.

Error responses

Errors follow the OAuth 2.0 standard shape:

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

Common values: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope, access_denied.

If PKCE values are missing or don't match, you will see one of:

invalid_request — "The PKCE protocol extension is required." (no code_challenge was sent on /authorize).

invalid_grant — "Failed to verify code_verifier." (the verifier sent on /oauth/token doesn't match the challenge from /authorize).

Important notes

PKCE is required for all clients, including server-side applications that hold a client_secret. Always send code_challenge + code_challenge_method=S256 on /authorize and code_verifier on /oauth/token.

Always include audience=https://api.navexa.io/api on /authorize requests, otherwise the access token will not be accepted by the Navexa API.

Keep the authorization code secret — it is single-use and short-lived (~10 minutes). Never log it or expose it in client-side code.

Keep the client_secret on the server. Native and single-page apps that cannot store a secret should still use this flow with PKCE, simply omitting client_secret from the token request.

Validate state on the redirect back to your redirect_uri to prevent CSRF.

When to use OAuth 2.0

You need to act on behalf of a Navexa user.

You're integrating Navexa into a third-party web or mobile application.

You need user-consented access to resources.

2. API Key Authentication

If you only need to access your own data, you can use an API Key instead of OAuth 2.0.

Generate an API Key from your account settings.

Using an API Key

Include your API Key in the x-api-key header:

curl --request GET \
  --url https://api.navexa.com.au/api/some-endpoint \
  --header "x-api-key: YOUR_API_KEY"

Important notes

API Keys grant access only to your own data.

API Keys do not expire — treat them like passwords. Rotate them if you suspect exposure.

Never commit API Keys to source control or expose them in client-side code.

When to use API Key Authentication

You're only accessing your own account's data.

You're writing personal automation or scripts.

You don't want to handle token refresh.

Authenticating with the Navexa API#

1. OAuth 2.0 Authorization Code Flow with PKCE#

Step 1 — Generate PKCE values#

Step 2 — Redirect the user to the authorization endpoint#

Step 3 — Exchange the authorization code for tokens#

Step 4 — Call the Navexa API#

Refreshing an access token#

Scopes#

Error responses#

Important notes#

When to use OAuth 2.0#

2. API Key Authentication#

Using an API Key#

Important notes#

When to use API Key Authentication#

Authenticating with the Navexa API

1. OAuth 2.0 Authorization Code Flow with PKCE

Step 1 — Generate PKCE values

Step 2 — Redirect the user to the authorization endpoint

Step 3 — Exchange the authorization code for tokens

Step 4 — Call the Navexa API

Refreshing an access token

Scopes

Error responses

Important notes

When to use OAuth 2.0

2. API Key Authentication

Using an API Key

Important notes

When to use API Key Authentication