API Reference

Register a client

If your account manager has not pre-provisioned a client, register one with dynamic client registration. You receive back a client_id (and a client_secret if you request a confidential client).

curl -X POST https://studio.flamel.ai/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Integration",
    "redirect_uris": ["https://your-app.example.com/callback"],
    "token_endpoint_auth_method": "client_secret_post"
  }'

For a public (PKCE-only) client, send "token_endpoint_auth_method": "none" and omit the secret on token exchange.

Send the user through authorization

Generate a PKCE code_verifier and its code_challenge (S256), then redirect the user to the authorization endpoint. After they approve the consent screen, Flamel redirects back to your redirect_uri with a code query parameter.

https://studio.flamel.ai/api/oauth/authorize
  ?response_type=code
  &client_id=<your_client_id>
  &redirect_uri=https://your-app.example.com/callback
  &code_challenge=<your_code_challenge>
  &code_challenge_method=S256
  &scope=flamel:full

Exchange the code for a bearer token

Post the authorization code and your PKCE code_verifier to the token endpoint:

curl -X POST https://studio.flamel.ai/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<authorization_code>" \
  -d "redirect_uri=https://your-app.example.com/callback" \
  -d "client_id=<your_client_id>" \
  -d "client_secret=<your_client_secret>" \
  -d "code_verifier=<your_code_verifier>"

The response contains your access_token. Include it in the Authorization header of every request:

Authorization: Bearer <your_access_token>

When the access token expires, request a new one with grant_type=refresh_token and the refresh_token from this response.

Confirm authentication

Use the MCP server's whoami tool (see below) to confirm your token works. It returns your authenticated user, active workspace, active hub, scope, and client ID:

{
  "user": { "_id": "...", "email": "you@example.com", "firstname": "...", "lastname": "..." },
  "workspace": { "_id": "...", "name": "Downtown Location" },
  "hub": { "_id": "...", "name": "Acme Franchising" },
  "scope": "flamel:full",
  "clientId": "<your_client_id>"
}