Skip to main content
The Lunacal MCP API uses the OAuth 2.0 authorization code flow. The user grants consent once in the Lunacal web app. Your client then receives a short-lived access token and a long-lived refresh token, so the user does not have to consent again while the refresh token is valid.

​
Tokens

​
Authorization flow

1

Redirect the user to the consent page

Open the user’s browser at the Lunacal authorization page:
  • redirect_uri — required. Must be registered for your client.
  • state — recommended. An opaque random string; it is returned unchanged so you can guard against CSRF.
2

The user approves access

The user signs in (if needed) and clicks Allow. Lunacal redirects the browser to your redirect_uri:
Verify that state matches the value you sent.
3

Exchange the code for tokens

Send the code to POST /api/mcp/token within 10 minutes. You receive an accessToken and a refreshToken.
4

Call the API

Include the access token on every request:
5

Refresh before expiry

When the access token expires (after 1 hour), call POST /api/mcp/refresh to get a new token pair.

​
Token rotation

Every call to /api/mcp/refresh rotates both tokens. The refresh token you submit is invalidated immediately.
Always store the new refresh token returned by /api/mcp/refresh. Reusing an old refresh token returns 400, and the user will need to grant consent again.

​
Security best practices

  • Keep your client secret on your server. Never ship it in browser or mobile code.
  • Store access and refresh tokens encrypted at rest.
  • Always send and verify the state parameter.
  • Refresh tokens proactively using the expiresAt value instead of waiting for a 401.