Skip to main content

​
OAuth Authentication

The Nerve API uses OAuth 2.0 for authentication. To get started, you’ll need to obtain your client credentials from our support team.
To get your OAuth client ID and secret, please contact our support team at [email protected]

​
OAuth Flow

The Nerve API follows the standard OAuth 2.0 authorization code flow. Here’s how it works:

​
1. Authorization Request

Redirect users to the authorization endpoint to begin the OAuth flow: 
GET https://api.usenerve.com/oauth/authorize
  ?client_id={YOUR_CLIENT_ID}
  &redirect_uri={YOUR_REDIRECT_URI}
  &response_type=code
  &scope={REQUESTED_SCOPES}
  &state={RANDOM_STATE}
Parameters:
  • client_id: Your application’s client ID (obtained from support)
  • redirect_uri: The URI where users will be redirected after authorization
  • response_type: Must be code for authorization code flow
  • scope: Space-separated list of requested permissions
  • state: A random string to prevent CSRF attacks

​
2. User Authorization

The user will be redirected to Nerve’s authorization page where they can:
  • Log in to their Nerve account
  • Review the permissions your application is requesting
  • Grant or deny access

​
3. Authorization Code

If the user grants access, they’ll be redirected back to your redirect_uri with an authorization code: 
https://your-app.com/callback?code={AUTHORIZATION_CODE}&state={STATE}

​
4. Exchange Code for Token

Exchange the authorization code for an access token: 
POST https://api.usenerve.com/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={YOUR_CLIENT_ID}
&client_secret={YOUR_CLIENT_SECRET}
&code={AUTHORIZATION_CODE}
&grant_type=authorization_code
&redirect_uri={YOUR_REDIRECT_URI}
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200...",
  "scope": "read write"
}

​
5. Using the Access Token

Include the access token in the Authorization header for all API requests: 
curl -H "Authorization: Bearer {ACCESS_TOKEN}" \
     https://api.usenerve.com/v1/endpoint

​
Token Refresh

Access tokens expire after a certain period. Use the refresh token to obtain a new access token: 
POST https://api.usenerve.com/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={YOUR_CLIENT_ID}
&client_secret={YOUR_CLIENT_SECRET}
&refresh_token={REFRESH_TOKEN}
&grant_type=refresh_token

​
Scopes

The following scopes are available for the Nerve API:
  • read: Read access to your Nerve data
  • write: Write access to create and update data
  • admin: Administrative access (if applicable)
Specific scope requirements may vary by endpoint. Check individual endpoint documentation for required permissions.

​
Error Handling

If authentication fails, the API will return appropriate HTTP status codes and error messages:
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or expired token
  • 403 Forbidden: Insufficient permissions
  • 500 Internal Server Error: Server error
Example error response: 
{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid or expired"
}