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.

Before you start

Navexa engineers set up every OAuth application by hand. Email help@navexa.com with the subject API Access Request and include:

Your company and application name

What your application does with Navexa data

The scopes you need

Your redirect URIs

We reply with your Client ID, your Client Secret and the scopes approved for your application. Email the same address to change your scopes or redirect URIs later.

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%20portfolios:read%20holdings:read%20transactions:read&
  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: the OpenID Connect scopes plus the Navexa scopes your application needs. 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.

The user signs in and sees a consent screen that lists the scopes you requested. After they approve, 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 portfolios:read holdings:read transactions:read"
}

refresh_token is only returned if offline_access was requested. id_token is only returned if openid was requested. scope lists what the user approved.

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, with the same scopes the user approved. 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

Scopes say what your application may do with a user's Navexa data. Request only what your application uses. To add a scope later, send the user through Step 2 again with the new list.

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.

Navexa scopes

Scope	Lets your application
`account:read`	See the user's plan and account limits
`portfolios:read`	See portfolios and custom groups
`portfolios:create`	Create portfolios
`portfolios:write`	Create, change and delete portfolios and custom groups
`holdings:read`	See holdings and custom prices
`holdings:write`	Change and delete holdings and custom prices
`transactions:read`	See trades, income and cash transactions
`transactions:write`	Add, change and delete trades, income and cash transactions
`tax:read`	See tax reports, tax settings and sale scenarios
`tax:write`	Change tax settings and saved sale scenarios
`performance:read`	See performance, benchmark, diversification and income reports
`clients:read`	See advice clients
`clients:write`	Add, change and delete advice clients

A write scope does not include its read scope. portfolios:write does include portfolios:create.

Each endpoint's page lists the scope it needs and the plans it is available on.

What your application can reach

An endpoint works when its scope is approved by both:

The user, on the consent screen.

Navexa, for your application. To change this, email help@navexa.com with your Client ID.

The user's plan still applies. A scope does not unlock a feature their plan does not include.

Error responses

Errors from /authorize and /oauth/token 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).

When the API refuses a call

A call your application is not allowed to make returns 403 Forbidden and changes nothing:

{
  "error": "scope_not_granted",
  "message": "The customer did not grant this app the scope this endpoint requires.",
  "requiredScope": "transactions:write"
}

`error`	Meaning	What to do
`scope_not_granted`	`requiredScope` is not approved for your application	Request it and send the user through Step 2
`connection_revoked`	The user disconnected your application	Send the user through Step 2 again
`client_disabled`	Navexa suspended your application	Email help@navexa.com
`partner_access_error`	Navexa could not check access	Retry with backoff

Users manage linked applications under Settings → Integrations → Connected Apps.

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.

Request Navexa scopes, not only the OpenID Connect scopes, so the consent screen tells users what your application does.

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.

Scopes do not apply to API Keys.

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#

Before you start#

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#

OpenID Connect scopes#

Navexa scopes#

What your application can reach#

Error responses#

When the API refuses a call#

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

Before you start

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

OpenID Connect scopes

Navexa scopes

What your application can reach

Error responses

When the API refuses a call

Important notes

When to use OAuth 2.0

2. API Key Authentication

Using an API Key

Important notes

When to use API Key Authentication