Approve an authorization request

POST

/oauth/authorize

curl --request POST \
  --url https://api.nsin.ir/oauth/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "client_id": "example", "redirect_uri": "example", "response_type": "code", "scope": "openid profile email offline_access", "state": "example", "code_challenge": "example", "code_challenge_method": "S256", "nonce": "example", "consent": true }'

• Production

The server side of the panel’s /oauth/authorize page. It is called by the NSIN panel with the signed-in user’s session, never by a relying party: your application’s part of this step is the browser redirect to {panel}/oauth/authorize?…, and the redirect back that follows.

Documented here because it defines the parameters your redirect must carry. state is required. PKCE is mandatory for every client: code_challenge_method must be S256 and code_challenge must be BASE64URL(SHA256(code_verifier)) with a verifier of 43–128 unreserved characters.

A first-party client is approved silently. A third-party client is approved once per scope set: the first request answers consent_required with the client’s name and the human descriptions of the scopes, and the panel repeats the request with consent: true.

Authorizations

• panelAuth

Request Body ^required

Media type application/json

object

client_id

required

string

redirect_uri

required

Must match one of the client’s registered URIs exactly.

string

response_type

required

string

Allowed values: code

scope

required

Space-separated. Must include openid.

string

Example

openid profile email offline_access

state

required

Opaque value echoed back on the redirect. Required.

string

code_challenge

required

string

code_challenge_method

required

string

Allowed values: S256

nonce

Echoed in the ID token.

string

consent

Set by the panel when the user approves a third-party client.

boolean

Responses

200

Either the URL to send the browser to, or a request for consent.

Media type application/json

One of:

object

object

redirect_to

The registered redirect_uri with code, state and iss appended.

string

object

object

consent_required

boolean

client

object

name

string

description

string

scopes

Array<object>

object

id

string

description

string

Example

{
  "redirect_to": "https://app.example/auth/callback?code=nac_…&state=xyz&iss=https%3A%2F%2Fapi.nsin.ir"
}

400

invalid_client, invalid_redirect_uri, unsupported_response_type, invalid_request (missing or malformed PKCE / state) or invalid_scope.

Media type application/json

The RFC 6749 error shape, used by the NSIN SSO endpoints only. It is deliberately different from Error: OAuth clients match on the machine error code, and only show error_description to a developer.

object

error

required

The machine-readable code.

string

error_description

A human-readable explanation. Never match on this.

string

Example

{
  "error": "invalid_grant",
  "error_description": "authorization code is invalid or expired"
}

401

No panel session, or a legacy session token with no session id.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

403

The account is not active.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}