Authorization

Browser-facing part of the authorization code flow: sign-in, consent, redirect back with a code.

Base URL, authentication and conventions of this API are on the OAuth & OpenID Connect API page.

Endpoints

get/oauth/authorizeStart the authorization code flow

get/oauth/authorize

Start the authorization code flow

Open this URL in the user's browser (not in an embedded web view). Nucleo:

shows the Nucleo sign-in page (/login) if the user has no session;
shows a consent screen naming your client and the requested scopes (Nucleo's own apps skip it). Self-registered clients see the consent screen the first time, and again whenever the person has no valid token of that client covering the requested scopes; send prompt=consent to always show it.;
redirects to redirect_uri with code and state — or with error=access_denied if the user clicks Cancel.

PKCE is required for public clients (token_endpoint_auth_method: none) and only S256 is advertised. Authorization codes are single-use and short-lived (10 minutes): exchange them immediately at /oauth/token.

redirect_uri must match exactly one of the URIs registered for the client. Errors that make the redirect unsafe (unknown client, unregistered redirect_uri) are shown to the user instead of being redirected.

GET https://auth.nucleoplatform.com/oauth/authorize

Authentication: None — public endpoint

Query parameters

response_typestringrequired
One ofcode
Example: code
client_idstringrequired
Example: 9d3f2b1c-6a4e-4f7b-9c2d-1e8a7b6c5d4f
redirect_uristring (uri)required
Example: https://assistant.acme.example/oauth/callback
scopestring
Space-separated. Unknown scopes are rejected with invalid_scope.

Example: openid profile email offline_access
statestring
Opaque value returned unchanged; strongly recommended against CSRF.

Example: af0ifjsldkj
code_challengestring
BASE64URL(SHA256(code_verifier)). Required for public clients.

min length 43max length 128
Example: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
code_challenge_methodstring
Send S256. If omitted, the challenge is treated as plain and an S256 verifier will fail at /oauth/token.

One ofS256
Example: S256
noncestring
OpenID Connect nonce, max 255 characters. Returned unchanged in the nonce claim of the ID token; check it there to bind the ID token to your sign-in request. A longer value is ignored without an error, and the ID token then has no nonce.

max length 255
Example: n-0S6_WzA2Mj
org_idinteger
Company id (orgs[].id in userinfo) the token should start in. Used only if the person belongs to that company and its access rules let them in; otherwise ignored without an error. It ends up in the org_id claim of the access token and of userinfo, is kept by every refresh, and the MCP connector uses it as the active company (active_company_source: claim). It is a hint, not a restriction: the token still works in every company of the person.

Example: 7
promptstring
login forces a new sign-in, consent forces the consent screen, none fails with login_required / consent_required instead of showing UI.

One ofnoneloginconsent
Example: login

Responses

200Sign-in page or consent screen (HTML).text/html
string
302Redirect. Either to /login (no session), or back to the client: https://assistant.acme.example/oauth/callback?code=def502…&state=af0ifjsldkj on approval, …?error=access_denied&error_description=…&state=af0ifjsldkj on denial; error=<code> (e.g. invalid_scope) on an invalid request.
Headers
- Location

Request

curl -X GET 'https://auth.nucleoplatform.com/oauth/authorize?response_type=code&client_id=9d3f2b1c-6a4e-4f7b-9c2d-1e8a7b6c5d4f&redirect_uri=https%3A%2F%2Fassistant.acme.example%2Foauth%2Fcallback&scope=openid%20profile%20email%20offline_access&state=af0ifjsldkj&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&nonce=n-0S6_WzA2Mj&org_id=7&prompt=login' \
  -H 'Accept: text/html'

const res = await fetch("https://auth.nucleoplatform.com/oauth/authorize?response_type=code&client_id=9d3f2b1c-6a4e-4f7b-9c2d-1e8a7b6c5d4f&redirect_uri=https%3A%2F%2Fassistant.acme.example%2Foauth%2Fcallback&scope=openid%20profile%20email%20offline_access&state=af0ifjsldkj&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&nonce=n-0S6_WzA2Mj&org_id=7&prompt=login", {
  method: "GET",
  headers: {
    Accept: "text/html",
  },
});
const data = await res.text();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://auth.nucleoplatform.com/oauth/authorize?response_type=code&client_id=9d3f2b1c-6a4e-4f7b-9c2d-1e8a7b6c5d4f&redirect_uri=https%3A%2F%2Fassistant.acme.example%2Foauth%2Fcallback&scope=openid%20profile%20email%20offline_access&state=af0ifjsldkj&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&nonce=n-0S6_WzA2Mj&org_id=7&prompt=login', [
    'headers' => [
        'Accept' => 'text/html',
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

Response

string

Was this page helpful?