Authentication

Exchange your Intuizi Console credentials for a bearer token, then send that token on every other call in the reference. The login endpoint is the only one that does not itself require a token.

Login

POST /api/v2/auth/login

Issues a bearer token for the supplied user credentials. Send the token on every subsequent request as Authorization: Bearer <token>.

Auth: none (this is how you obtain a token). Send Content-Type: application/json and Accept: application/json. Rate limit: 180 requests/min per client IP - login sits outside the v2 group and is metered by the shared API throttle keyed per IP, not by the per-token v2 write bucket. Failed logins are limited per email, see Failed logins.

Body

curl -X POST "https://console.intuizi.com/api/v2/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/auth/login",
    headers={"Content-Type": "application/json", "Accept": "application/json"},
    json={"email": "you@example.com", "password": "your-password"},
)
token = res.json()["data"]["token"]

const res = await fetch("https://console.intuizi.com/api/v2/auth/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({ email: "you@example.com", password: "your-password" }),
});
const token = (await res.json()).data.token;

$res = Http::acceptJson()->post(
    'https://console.intuizi.com/api/v2/auth/login',
    ['email' => 'you@example.com', 'password' => 'your-password']
);
$token = $res->json('data.token');

Response

{
  "status": "success",
  "code": 200,
  "message": "Token generated successfully.",
  "data": {
    "token": "FxGrKXTS0iLgonnQZtELC0dWu73xslzHjGjaBVef"
  }
}

Failed requests use the shared error envelope - see Errors.

Login tokens rotate. Each successful login deletes the account’s previous login token - one live login token per account - and the token is also revoked when the user logs out of the console or changes their password, and when an administrator ends the user’s console sessions or deactivates the account. For CLI sessions, CI pipelines, and any long-lived integration, use an API token instead: API tokens are not rotated by logins and survive logout.

Failed logins

Every endpoint on this page that takes an email and a password (login, and creating or revoking API and MCP tokens) checks them the same way and counts failed attempts together:

• Only an active, confirmed account can log in. A wrong email or password, and an account that is deactivated or not yet confirmed, all get the same 401.
• After 5 failed attempts for one email from one IP address within a minute, or 20 for one email from any address within an hour, these endpoints answer 429 for that email, whatever the password, until the Retry-After header’s seconds have passed.
• Only failures count, so a client that logs in on every run is not limited. A successful login clears the per-minute count for that email from that IP address. The hourly count for the email runs until its hour is up, even when a login succeeds in between. A client that gets a 401 should stop and fix its credentials rather than retry.

The limits are listed on Limits, and the 429 envelope on Errors.

Sending the token

Every other endpoint in this reference is authenticated and JSON-only. Send both headers on every call:

Authorization: Bearer <YOUR_TOKEN>
Accept: application/json

A missing, invalid, or expired token returns 401. A request that omits Accept: application/json returns 406. POST bodies must also send Content-Type: application/json (or multipart/form-data for file uploads).

Create MCP Token

POST /api/v2/auth/mcp-token

Issues a long-lived bearer token (scope: mcp) for the MCP server. MCP tokens are independent of login tokens: logins do not rotate them and console logout does not revoke them. Changing the account password or deactivating the account revokes all MCP tokens. They expire after one year by default. Up to 10 can be active at once; further requests return a 422 until you revoke.

The primary way to manage MCP tokens is the My Account > MCP Tokens page in the Intuizi console; this endpoint exists for CLI and headless use.

Auth: none (credential exchange). Send Content-Type: application/json and Accept: application/json. Rate limit: 10 requests/min by default. Failed attempts count toward the failed-login limit.

Body

curl -X POST "https://console.intuizi.com/api/v2/auth/mcp-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/auth/mcp-token",
    headers={"Content-Type": "application/json", "Accept": "application/json"},
    json={"email": "you@example.com", "password": "your-password"},
)
token = res.json()["data"]["token"]

const res = await fetch("https://console.intuizi.com/api/v2/auth/mcp-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({ email: "you@example.com", password: "your-password" }),
});
const token = (await res.json()).data.token;

$res = Http::acceptJson()->post(
    'https://console.intuizi.com/api/v2/auth/mcp-token',
    ['email' => 'you@example.com', 'password' => 'your-password']
);
$token = $res->json('data.token');

Response

{
  "status": "success",
  "code": 200,
  "message": "MCP token generated successfully.",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJh...",
    "expires_at": "2027-07-18T00:00:00+00:00"
  }
}

Failed requests use the shared error envelope - see Errors.

Revoke MCP Tokens

POST /api/v2/auth/mcp-token/revoke

Revokes every active MCP token owned by the supplied credentials. Connected MCP clients stop authenticating immediately.

The primary way to manage MCP tokens is the My Account > MCP Tokens page in the Intuizi console, which also revokes tokens individually; this endpoint exists for CLI and headless use and is all-or-nothing.

Auth: none (credential exchange). Send Content-Type: application/json and Accept: application/json. Rate limit: 10 requests/min by default. Failed attempts count toward the failed-login limit.

Body

curl -X POST "https://console.intuizi.com/api/v2/auth/mcp-token/revoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/auth/mcp-token/revoke",
    headers={"Content-Type": "application/json", "Accept": "application/json"},
    json={"email": "you@example.com", "password": "your-password"},
)
revoked = res.json()["data"]["revoked"]

const res = await fetch("https://console.intuizi.com/api/v2/auth/mcp-token/revoke", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({ email: "you@example.com", password: "your-password" }),
});
const revoked = (await res.json()).data.revoked;

$res = Http::acceptJson()->post(
    'https://console.intuizi.com/api/v2/auth/mcp-token/revoke',
    ['email' => 'you@example.com', 'password' => 'your-password']
);
$revoked = $res->json('data.revoked');

Response

{
  "status": "success",
  "code": 200,
  "message": "MCP tokens revoked successfully.",
  "data": {
    "revoked": 2
  }
}

Failed requests use the shared error envelope - see Errors.

Create API Token

POST /api/v2/auth/api-token

Issues a long-lived bearer token (name: api, no scopes) that authenticates every general v2 endpoint except POST /api/v2/mcp, which requires the mcp scope and rejects api tokens with 403 insufficient_scope. Tokens expire after one year by default. Up to 10 can be active at once; beyond that, minting returns a 422 with API token limit reached (10 active tokens). Revoke existing tokens via POST /api/v2/auth/api-token/revoke and retry.

API tokens are long-lived bearer tokens for the Intuizi CLI, CI pipelines, and custom integrations. They are not rotated by logins, survive console logout, and are revoked on password change, when the account is deactivated, on explicit revocation, or at expiry. Each account can hold up to 10 active API tokens. Manage them under My Account > API Tokens in the console, where CI tokens should be minted. In CI, pass the token via the INTUIZI_API_TOKEN environment variable rather than calling the mint endpoint on every run.

Auth: none (credential exchange). Send Content-Type: application/json and Accept: application/json. Rate limit: 10 requests/min by default. Failed attempts count toward the failed-login limit.

Body

curl -X POST "https://console.intuizi.com/api/v2/auth/api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/auth/api-token",
    headers={"Content-Type": "application/json", "Accept": "application/json"},
    json={"email": "you@example.com", "password": "your-password"},
)
token = res.json()["data"]["token"]

const res = await fetch("https://console.intuizi.com/api/v2/auth/api-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({ email: "you@example.com", password: "your-password" }),
});
const token = (await res.json()).data.token;

$res = Http::acceptJson()->post(
    'https://console.intuizi.com/api/v2/auth/api-token',
    ['email' => 'you@example.com', 'password' => 'your-password']
);
$token = $res->json('data.token');

Response

{
  "status": "success",
  "code": 200,
  "message": "API token generated successfully.",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJh...",
    "expires_at": "2027-07-28T00:00:00+00:00"
  }
}

Failed requests use the shared error envelope - see Errors.

Revoke API Tokens

POST /api/v2/auth/api-token/revoke

Revokes every active API token owned by the supplied credentials. Connected CLI sessions, CI pipelines, and integrations stop authenticating immediately.

The primary way to manage API tokens is the My Account > API Tokens page in the Intuizi console, which also revokes tokens individually. This endpoint is for headless use and is all-or-nothing: it also revokes the tokens that CI pipelines and the Intuizi CLI use.

Auth: none (credential exchange). Send Content-Type: application/json and Accept: application/json. Rate limit: 10 requests/min by default. Failed attempts count toward the failed-login limit.

Body

curl -X POST "https://console.intuizi.com/api/v2/auth/api-token/revoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/auth/api-token/revoke",
    headers={"Content-Type": "application/json", "Accept": "application/json"},
    json={"email": "you@example.com", "password": "your-password"},
)
revoked = res.json()["data"]["revoked"]

const res = await fetch("https://console.intuizi.com/api/v2/auth/api-token/revoke", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({ email: "you@example.com", password: "your-password" }),
});
const revoked = (await res.json()).data.revoked;

$res = Http::acceptJson()->post(
    'https://console.intuizi.com/api/v2/auth/api-token/revoke',
    ['email' => 'you@example.com', 'password' => 'your-password']
);
$revoked = $res->json('data.revoked');

Response

{
  "status": "success",
  "code": 200,
  "message": "API tokens revoked successfully.",
  "data": {
    "revoked": 2
  }
}

Failed requests use the shared error envelope - see Errors.

OAuth one-click connect

The MCP server additionally supports OAuth 2.1 with the authorization-code + PKCE flow. This is how any OAuth-capable client connects, whether it is a command-line tool or a UI that adds MCP servers as custom connectors: it takes a server URL only, discovers the authorization server, registers itself, and sends you to an Intuizi consent screen in the browser. You never handle a credential. A client configured with a static Authorization header never reaches this flow, because it does not receive the 401 challenge that bootstraps it. For the user-facing walkthrough see Getting started; this section documents the protocol surface for client implementers.

Discovery

Both discovery documents are public JSON, and they are the source of truth for the supported scopes, grant types, and endpoint URLs - read them rather than hardcoding values:

• Protected-resource metadata (RFC 9728): https://console.intuizi.com/.well-known/oauth-protected-resource
• Authorization-server metadata (RFC 8414): https://console.intuizi.com/.well-known/oauth-authorization-server

An unauthenticated request to the MCP endpoint returns 401 with a WWW-Authenticate header pointing at the protected-resource document, so a compliant client can bootstrap the whole flow from the server URL alone.

Endpoints

Only an active, confirmed account can approve a connection. While you are logged in as another user in the console, the consent screen and its approval answer 403 with access_denied, and no connection is made. Return to your own account to connect an application.

Registration constraints

Registration is open to OAuth clients but tightly constrained, because the redirect target is what protects the authorization code:

• redirect_uris must be exact, absolute https URIs on an approved host list (the major agent platforms are pre-approved). No wildcards, fragments, or userinfo.
• A redirect URI may contain only letters, digits and - . _ ~ : / ? [ ] = & + ; ! $ ' ( ). A backslash, comma, @, %, #, space or control character is rejected. The host must be a plain host name with an optional port from 1 to 65535: no trailing dot and no empty port.
• Loopback redirects (localhost, 127.0.0.1, [::1]) are exempt from the host list and may use plain http on any port. This is the form command-line and desktop clients use to receive the authorization code, so they connect without any host being added.
• Registered clients can use only the authorization_code and refresh_token grant types and the mcp scope. Any other scope, including the wildcard *, is rejected with invalid_scope.
• Errors use the standard RFC 7591 shape (error / error_description), not the v2 envelope.

If your client’s redirect host is rejected, contact your Account Manager to have it reviewed and added.

PKCE

PKCE is required for every authorization request, and only the S256 challenge method is accepted - requests without a code_challenge, or using the plain method, are rejected. This applies to confidential clients too, per OAuth 2.1.

Token lifetimes

• Access tokens live 1 hour and carry the mcp scope.
• Refresh tokens live 60 days and rotate: each refresh returns a new pair and invalidates the old one.
• A refresh token that was rotated out, revoked, or expired is rejected with 400 and error: invalid_grant (RFC 6749). Discard the stored tokens and send the user through authorization again.
• Manual MCP tokens (the Create MCP Token path) are unchanged: one year, separate cap, separate lifecycle.

Revocation

A connection ends when any of these happens:

• the client calls POST /oauth/revoke with the access or refresh token (revoking either half invalidates both).
• the refresh token expires (60 days) without renewal.
• you change your Intuizi console password, which immediately revokes every token on the account: login tokens, API tokens, MCP tokens, and every OAuth connection.
• an administrator deactivates your account or withdraws its confirmation, which revokes every token on the account in the same way. Reactivating the account does not restore them.
• your organization is deleted, which revokes every token of every account in it in the same way.

Console logins and logouts never affect OAuth connections or MCP tokens.