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

# OAuth 2.1

> OAuth authorization for third-party applications and MCP connections

# OAuth 2.1

Nico implements an OAuth 2.1 authorization server for third-party applications and MCP server connections.

## Overview

OAuth 2.1 allows external applications to access your Nico account with your permission, without sharing your password. This is how AI assistants connect to the [MCP server](/integrations/mcp-server).

The authorization server runs at:

```
https://mcp.nico-jobagent.com
```

## Client registration

Nico supports **Dynamic Client Registration** (RFC 7591): MCP clients such as ChatGPT and Claude register themselves automatically when you add the connector — you don't need to enter a client ID or secret. Leave any OAuth client fields blank and the client will self-register at `POST /oauth/register`.

<Note>
  Registered clients are **public clients** — there is no client secret; the flow is secured by PKCE instead (see below). Self-registered clients that request `client_secret_basic` receive a secret at registration time.
</Note>

## Discovery

Nico publishes an OAuth metadata document following RFC 8414:

```
GET https://mcp.nico-jobagent.com/.well-known/oauth-authorization-server
```

This returns all endpoints, supported grant types, and available scopes.

## Authorization flow

Nico uses the **authorization code** grant type with mandatory PKCE (`S256`):

```mermaid theme={null}
sequenceDiagram
    participant App as Your Application
    participant User as You
    participant Nico as Nico Authorization Server

    App->>Nico: 1. Redirect to /oauth/authorize (with PKCE challenge)
    Nico->>User: 2. Show consent screen
    User->>Nico: 3. Approve access
    Nico->>App: 4. Redirect with authorization code
    App->>Nico: 5. POST /oauth/token with code + PKCE verifier
    Nico->>App: 6. Return access token
```

Access tokens expire after 1 hour; a refresh token is issued alongside so clients can renew access without re-prompting you.

### Endpoints

| Endpoint                                                               | Method | Description                                     |
| ---------------------------------------------------------------------- | ------ | ----------------------------------------------- |
| `https://app.nico-jobagent.com/oauth/authorize`                        | GET    | Authorization endpoint — redirect users here    |
| `https://mcp.nico-jobagent.com/oauth/token`                            | POST   | Token endpoint — exchange code for access token |
| `https://mcp.nico-jobagent.com/oauth/revoke`                           | POST   | Revocation endpoint — invalidate a token        |
| `https://mcp.nico-jobagent.com/oauth/register`                         | POST   | Dynamic client registration (RFC 7591)          |
| `https://mcp.nico-jobagent.com/.well-known/oauth-authorization-server` | GET    | OAuth metadata discovery (RFC 8414)             |
| `https://mcp.nico-jobagent.com/.well-known/oauth-protected-resource`   | GET    | Protected resource metadata (RFC 9728)          |

<Note>
  The authorization endpoint lives on the app origin because it's interactive — it shows the login and consent screens using your existing Nico session. The non-interactive endpoints (token, revocation) stay on the MCP host. Clients that use the discovery document get the correct URLs automatically.
</Note>

## Scopes

| Scope   | Description                                |
| ------- | ------------------------------------------ |
| `read`  | Read access to your account data (default) |
| `write` | Create and update data in your account     |
| `mcp`   | Access the MCP server tools                |

<Note>
  The MCP server requires the `mcp` scope. Without it, MCP tool calls will be rejected.
</Note>

## Managing grants

You can view and revoke OAuth grants in your account:

* **View active grants:** See which applications have access to your account
* **Revoke a grant:** Remove an application's access immediately

### API endpoints for grant management

| Endpoint                | Method | Description                   |
| ----------------------- | ------ | ----------------------------- |
| `/api/oauth_grants`     | GET    | List your active OAuth grants |
| `/api/oauth_grants/:id` | DELETE | Revoke a specific grant       |

## For MCP connections

If you're connecting an AI assistant via MCP, point it at:

```
https://mcp.nico-jobagent.com/mcp
```

and leave the OAuth client fields blank — the assistant registers itself and handles the OAuth flow for you. You'll see a consent screen asking you to approve access — click **Authorize** to connect.

The resulting token is stored by the MCP client (e.g., Claude Desktop) and used automatically for future requests. See [MCP Server](/integrations/mcp-server) for setup details per assistant.