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

# Authenticate with the Navis Ops API

> Learn the two ways to authenticate with the Navis Ops API — API keys for quick setup and OAuth 2.1 for clients that manage tokens automatically.

Every request to the Navis Ops API and MCP server must include a valid bearer token. Navis Ops supports two authentication methods: API keys for straightforward integrations and OAuth 2.1 for clients that handle the authorization flow themselves. Both methods produce a token you pass in the same `Authorization` header, so the rest of your integration code is identical regardless of which method you choose.

## Choosing an authentication method

<CardGroup cols={2}>
  <Card title="API Keys" icon="key" href="/api-reference/authentication/api-keys">
    Create a token in Settings and copy it once. Works with any HTTP client or AI assistant. Best when you control the environment and can store the token securely.
  </Card>

  <Card title="OAuth 2.1" icon="lock" href="/api-reference/authentication/oauth">
    Let your client handle the authorization flow automatically. Recommended for AI clients like Claude Desktop and Cursor that natively support MCP OAuth.
  </Card>
</CardGroup>

### When to use each method

|                            | API Keys                           | OAuth 2.1                                  |
| -------------------------- | ---------------------------------- | ------------------------------------------ |
| Setup time                 | \~30 seconds                       | Automatic via client                       |
| Works with any HTTP client | Yes                                | Depends on client support                  |
| Token rotation             | Manual                             | Automatic                                  |
| Recommended for            | Scripts, CI, manual integrations   | Claude Desktop, Cursor, MCP-native clients |
| Revocation                 | Settings → Connected Apps → Revoke | Settings → Connected Apps → Disconnect     |

## Sending a request

Both methods use the same `Authorization` header format. Include your token as a bearer credential on every request:

```bash theme={null}
Authorization: Bearer nops_your_token_here
```

Here is a complete example using curl:

```bash theme={null}
curl https://<your-supabase-project>.supabase.co/functions/v1/mcp-server-v2 \
  -H "Authorization: Bearer nops_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

OAuth access tokens use the same header format — replace the `nops_` prefixed API key with your OAuth bearer token.

## Error responses

If your request fails authentication or authorization, Navis Ops returns one of two error codes:

<AccordionGroup>
  <Accordion title="401 Unauthorized — token missing or invalid">
    Your request did not include a token, or the token could not be validated (wrong value, revoked, or expired). Check that the `Authorization` header is present and that the token value is correct.

    ```json theme={null}
    {
      "error": "unauthorized",
      "message": "Missing or invalid authorization token."
    }
    ```

    Common causes:

    * The `Authorization` header is missing entirely
    * The token was revoked in **Settings → Connected Apps**
    * An OAuth access token expired and was not refreshed
    * The token value has a typo or was truncated at copy time
  </Accordion>

  <Accordion title="403 Forbidden — valid token, insufficient scope">
    Your token is valid but does not have the scope required for the operation. Read-only tokens (`mcp:read`) cannot call write tools.

    ```json theme={null}
    {
      "error": "forbidden",
      "message": "This operation requires the mcp:write scope."
    }
    ```

    To resolve this: create a new API key with **Read + Write** enabled, or disconnect and reconnect your OAuth client approving the `mcp:write` scope.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Create an API key" icon="key" href="/api-reference/authentication/api-keys">
    Generate a token from Settings in under a minute.
  </Card>

  <Card title="Set up OAuth 2.1" icon="lock" href="/api-reference/authentication/oauth">
    Use OAuth for clients that support the MCP authorization flow.
  </Card>
</CardGroup>