Nexus Authentication
How to obtain and use access tokens to consume Nexus APIs
ⓘ
Overview
▼
The Nexus platform exposes a public OAuth2 token endpoint. Use your App Client credentials (client_id and client_secret) with the Client Credentials flow to obtain an access token. POST /nexus/oauth2/token does not require a Bearer token — Nexus Auth validates your App Client and returns the access token for use with Nexus APIs.
Your App
→ credentials →
Nexus Auth
→ token →
Your App
→ Bearer →
Nexus APIs
1
Obtain Your Credentials
▼
The Nexus UI generates your credentials when you create an App Client on the App Clients screen. You will receive:
| Parameter | Description |
|---|---|
| client_id | Your App Client identifier |
| client_secret | Secret generated when the App Client is created |
The client_secret is shown only once at creation. Copy and store it immediately — it cannot be viewed again in the Nexus UI.
Never expose your client_secret in client-side code, public repositories, or logs. Treat it like a password.
2
Request an Access Token
▼
Send a POST request to /nexus/oauth2/token with Content-Type application/x-www-form-urlencoded and grant_type=client_credentials. Credentials can be supplied in two ways (RFC 6749 §2.3):
Preferred — Basic Authentication (curl -u shorthand):
curlcurl -X POST https://qa.api.nuvy.ai/nexus/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
-d "grant_type=client_credentials"
Fallback — client_id and client_secret in the request body (when the Authorization header is not used):
curlcurl -X POST https://qa.api.nuvy.ai/nexus/oauth2/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"
When Authorization: Basic is present, body client_id and client_secret are ignored. An optional scope parameter (space-separated) can be included in the body; if omitted, your App Client defaults apply.
3
Receive the Token
▼
A successful request returns a JSON response with the access token:
JSON{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "..."
}
| Field | Description |
|---|---|
| access_token | The JWT token to use in API requests |
| token_type | Always "Bearer" |
| expires_in | Token lifetime in seconds |
| scope | Granted scopes (when included in the response) |
4
Use the Token
▼
Include the access token in the Authorization header of every protected Nexus API request:
curlcurl -X GET https://qa.api.nuvy.ai/nexus/routes \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..."
5
Code Examples
▼
Node.js
JavaScriptconst response = await fetch('https://qa.api.nuvy.ai/nexus/oauth2/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': 'Basic ' + btoa(clientId + ':' + clientSecret)
},
body: 'grant_type=client_credentials'
});
const { access_token } = await response.json();
Python
Pythonimport requests
from requests.auth import HTTPBasicAuth
response = requests.post(
'https://qa.api.nuvy.ai/nexus/oauth2/token',
auth=HTTPBasicAuth(client_id, client_secret),
data={'grant_type': 'client_credentials'}
)
access_token = response.json()['access_token']
Java
JavaString credentials = Base64.getEncoder()
.encodeToString((clientId + ":" + clientSecret).getBytes());
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://qa.api.nuvy.ai/nexus/oauth2/token"))
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Authorization", "Basic " + credentials)
.POST(BodyPublishers.ofString("grant_type=client_credentials"))
.build();
HttpResponse<String> response = client.send(request,
BodyHandlers.ofString());
6
Token Renewal
▼
Tokens are short-lived. Your application should:
- Cache the token and reuse it until it expires
- Monitor the expires_in value and request a new token before expiration
- Handle 401 responses by requesting a fresh token and retrying the request
Do NOT request a new token for every API call. Cache and reuse until expiration.
7
Error Handling
▼
| Status | Description | Action |
|---|---|---|
| 400 | invalid_request — wrong Content-Type or missing credentials | Use Content-Type: application/x-www-form-urlencoded and send credentials via Basic or body |
| 400 | unsupported_grant_type — missing or wrong grant_type | Set grant_type=client_credentials |
| 400 | invalid_scope — requested scope not granted to the client | Remove scope or request only scopes configured for your App Client |
| 401 | invalid_client — invalid credentials or revoked App Client | Verify client_id and client_secret |
| 501 | unsupported_grant_type — grant type not supported for your App Client | Contact Nuvy support |
8
Security Best Practices
▼
- Store credentials in environment variables or a secrets manager, never in source code
- Use HTTPS for all requests (enforced by Nuvy API)
- Rotate your client_secret periodically
- Implement token caching to minimize token requests
- Never log access tokens or credentials
⚙
Environments
▼
| Environment | Token Endpoint |
|---|---|
| QA | https://qa.api.nuvy.ai/nexus/oauth2/token |
| Production | https://prd.api.nuvy.ai/nexus/oauth2/token |
Use the QA environment for development and testing. Switch to Production only when ready for go-live.
API Reference
Technical specification for the Nexus OAuth2 token endpoint
POST
https://qa.api.nuvy.ai/nexus/oauth2/token
Public endpoint — no Bearer token required. Nexus Auth issues an access token via client_credentials using your App Client credentials.
Authentication
| Type | Details |
|---|---|
| Preferred | Authorization: Basic with Base64-encoded client_id:client_secret |
| Fallback | client_id and client_secret in the form body (required when Basic is not used) |
Headers
| Header | Value | Required |
|---|---|---|
| Content-Type | application/x-www-form-urlencoded | Yes |
| Authorization | Basic {base64(client_id:client_secret)} | Preferred |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| grant_type | string | Yes | Must be client_credentials |
| client_id | string | If no Basic | Your App Client identifier |
| client_secret | string | If no Basic | Your App Client secret |
| scope | string | No | Space-separated scopes; App Client defaults apply if omitted |
Response (200 OK)
JSON{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "..."
}
Error Responses
| Status | Meaning |
|---|---|
| 400 Bad Request | invalid_request — wrong Content-Type or missing credentials |
| 400 Bad Request | unsupported_grant_type — invalid or missing grant_type |
| 400 Bad Request | invalid_scope — scope not granted to the client |
| 401 Unauthorized | invalid_client — invalid credentials or revoked App Client |
| 501 Not Implemented | unsupported_grant_type — grant type not supported for your App Client |
curl Generator
Enter your credentials to generate a ready-to-use curl command. Copy and run it in your terminal.
This tool only generates the command locally. Your credentials are never sent to any server from this page.