Authentication

Nevlo uses OAuth 2.0 with PKCE for all API and MCP access. MCP clients such as Claude Desktop handle the OAuth flow automatically.

OAuth 2.0 (Authorization Code + PKCE)

1. Client Registration

MCP clients register automatically via Dynamic Client Registration (RFC 7591). For your own apps:

POST /oauth/register

POST /oauth/register
Content-Type: application/json

{
  "client_name": "Meine App",
  "redirect_uris": ["https://meine-app.de/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}

// Response:
{
  "client_id": "nevlo_abc123...",
  "client_name": "Meine App",
  "redirect_uris": ["https://meine-app.de/callback"]
}

2. Discovery Endpoints

GET

GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource

3. Authorization Request

Browser Redirect

GET /oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=read:transactions read:accounts read:cashflow
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256

4. Token Exchange

POST /oauth/token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&code_verifier=ORIGINAL_VERIFIER

5. Token Refresh

POST /oauth/token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

6. API call with token

cURL

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://nevlo.io/api/v1/snapshot

Token lifetime: Access Token: 1 hour, Refresh Token: 30 days (rotating). PKCE (S256) is mandatory for all clients.

Scopes

read:transactionsRead and search transactions

read:accountsRead accounts and balances

read:cashflowCash flow, subscriptions, financial snapshot