Skip to main content

Resolve a caller's attributes and groups​

Answers "who is the principal behind this token" so a policy can decide on group membership and directory attributes rather than only on what the token happens to carry.

One endpoint over BOTH identity planes, resolved in order: a SlashID person by id, then an identity in the NHI graph by connection subject, then — only as a fallback — a UNIQUE email-claim match. An ambiguous email resolves to nothing, because an authorization decision must never rest on a guessed identity.

No x-rbac-enabled: the caller is a gate process, not a console session. Authenticated with the same org API key gate already holds, so enabling attribute conditions provisions no new credential.

A caller that matches nothing is a 200 with resolved: false, not a 404: "we looked and found nobody" is an answer, and gate caches it briefly so an unknown subject cannot hammer this endpoint. A 404 would be indistinguishable from the endpoint being unreachable, which is the case gate must handle differently.

Header Parameters
  • SlashID-OrgID string required

    The organization ID

    Example: af5fbd30-7ce7-4548-8b30-4cd59cb2aba1
Request Body required
  • verified boolean

    Default value: false

    Whether a plugin cryptographically VERIFIED the token these values came from. Resolution requires it: the subject on an unverified token is a value the caller chose, so resolving attributes for it would let them select whose permissions they receive. Gate already refuses to call this endpoint without verification; this field is what lets the endpoint refuse too, rather than trusting its caller to have checked. Absent counts as false.

  • issuer string

    The token's iss. Part of the identity, not decoration: two IdPs can each mint a token whose subject is "alice", and they are different people.

  • subject string required

    The token's sub. Gate only sends this for a token whose signature a plugin VERIFIED — an unverified sub is a value the caller chose.

  • claims object

    The remaining decoded claims, used only for the email fallback when neither the person id nor a connection subject matches.

Responses

The lookup completed. Read result.resolved — 200 covers both "found" and "matched nobody".

Schema
  • meta object
  • pagination object
  • limit integer
  • offset integer
  • total_count int64
  • cursor_pagination object

    Cursors are opaque. Follow the tokens the server returns; never construct, parse or modify one.

  • limit integer
  • next_cursor string

    Opaque token addressing the next page. Absent on the last page.

  • prev_cursor string

    Opaque token addressing the previous page. Absent on the first page.

  • last_cursor string

    Opaque token addressing the final page directly, so a client can jump to the end without a total count.

  • total_count int64

    Total number of matching items. Returned on the FIRST page only; clients cache it for the remainder of the walk.

  • errors object[]
  • httpcode integer
  • message string
  • code string

    Machine-readable reason, present only for errors that define one. Values today: unserved_org_region (the organization is homed in a region this deployment does not serve), wrong_region (the request must be sent to the organization's home region), region_route_missing (this instance has no route to the organization's home region).

  • result object

    What SlashID knows about a caller.

    resolved is a POSITIVE assertion, and a false answer carries no attributes and no groups — so a consumer cannot mistake "we could not look this caller up" for "this caller has nothing".

  • resolved boolean
  • source string

    Possible values: [im, graph]

    Which plane answered: im for a SlashID person, graph for an identity in the NHI graph. Absent when unresolved.

  • match_basis string

    Possible values: [person_id, connection_subject, email_claim]

    HOW the caller was matched, reported so an operator debugging a surprising decision can see whether the match was exact or a fallback. Absent when unresolved.

  • attributes object

    The caller's attributes. Buckets the end user can write themselves are excluded: a policy keyed on a value its own subject can set is self-service privilege escalation.

  • groups string[]
  • tags string[]

    The NAMES of the entity tags applied to the caller's identity in the NHI graph. Names rather than ids, because a policy naming a tag id is unreadable and a tag renamed keeps its id — the operator writes the name they see in the graph.

    Only the graph plane answers these; a SlashID person matched on the im plane carries none, and reports an empty list rather than omitting the key, for the same reason groups does.

  • person_id string

    Present only when the caller matched a SlashID person.

  • cache_ttl_seconds integer

    How long gate may reuse this answer. Zero means "no opinion" — gate substitutes its configured default rather than treating the answer as immediately stale.