Identify the calling credential

GET

/whoami

const url = 'https://api.nsin.ir/whoami';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.nsin.ir/whoami \
  --header 'Authorization: Bearer <token>'

Says who the caller is and what kind of credential it used — never any profile data. Use it to check a key before relying on it: whether it is read-only, which account it acts for, and — for a credential issued through NSIN SSO (an access token, or an nsin_ key an app minted with one) — which domains it may touch.

Works with an API key, an NSIN SSO access token (with or without the nsin:full scope — this is one of the two endpoints an identity-only token may call) and a panel session. A credential bound to an SSO client reports domain_access; when the user has revoked the app, grant_revoked is true and the selection is empty, which is how a connected app learns it was disconnected without guessing from 404s.

Authorizations

Responses

200

The caller’s identity.

application/json

The calling credential, as GET /whoami resolves it.

object

user_id

required

The account the credential acts for.

integer

auth

required

Kind of credential: key an nsin_ API key, sso an NSIN SSO access token, jwt the panel’s own session.

string

Allowed values: key sso jwt

read_only

required

true only for a read-only API key. SSO tokens are limited by scope and domain selection, not read-limited, so they report false.

boolean

admin

required

Whether the account is NSIN staff.

boolean

key_id

The API key’s id. Present only when auth is key.

integer

client_id

The NSIN SSO client the credential is bound to: the client an SSO token was issued to, or the app that minted this API key. Absent for keys you created yourself in the panel.

string

scope

Space-separated scopes granted to an SSO token. Present only when auth is sso.

string

domain_access

The domains a client-bound credential may touch. Absent for panel sessions and for keys you created yourself, which carry no domain restriction.

object

all

required

boolean

domain_ids

Array<integer>

domains

Array<object>

object

integer

name

string

grant_revoked

Present, and true, when the user has revoked the SSO grant behind this credential: it can no longer see any domain.

boolean

Examples

{
  "user_id": 42,
  "auth": "key",
  "read_only": true,
  "admin": false,
  "key_id": 7
}

{
  "user_id": 42,
  "auth": "sso",
  "read_only": false,
  "admin": false,
  "client_id": "my-app",
  "scope": "openid profile nsin:full",
  "domain_access": {
    "all": false,
    "domain_ids": [
      12
    ],
    "domains": [
      {
        "id": 12,
        "name": "example.com"
      }
    ]
  }
}

401

Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

limited

{
  "error": "rate limit exceeded"
}