> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenerve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Nerve API using OAuth

## 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.

<Note>
  To get your OAuth client ID and secret, please contact our support team at
  [support@usenerve.com](mailto:support@usenerve.com)
</Note>

## 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:

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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)

<Note>
  Specific scope requirements may vary by endpoint. Check individual endpoint
  documentation for required permissions.
</Note>

## 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:

```json theme={null}
{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid or expired"
}
```