Return the current principal's profile.

GET

/v1/auth/me

curl --request GET \
  --url https://example.com/v1/auth/me \
  --header 'Authorization: Bearer <token>'

Authorizations

• bearerAuth

Responses

200

Response for GET /auth/me.

Media typeapplication/json

Response for GET /auth/me.

object

isAdmin

required

Whether the principal has admin privileges.

boolean

sub

required

Principal subject identifier (UUID string).

string

surface

Any of:

object

The surface a token was issued to, as GET /auth/me reports it.

object

actions

required

The actions the surface declares: everything a token issued to it may do on the user’s behalf.

Array<string>

mountPath

Where the surface is served now. It may differ from where it was served when the token was issued: a mount path can change while the name, and so the token, stays valid.

string | null

name

required

Canonical name of the surface (acme.crm:app): the identity the token carries.

string

null

null

Example^generated

{
  "isAdmin": true,
  "sub": "example",
  "surface": {
    "actions": [
      "example"
    ],
    "mountPath": "example",
    "name": "example"
  }
}

default

Structured error envelope (SPEC-DATA-0006): {"errors": [{"domain", "scope", "target", "code", "message"}, ...]}. domain (added #950 D9) names the subsystem that produced the entry (data, metadata, apply, git, auth, iam, hfx, or api for a transport-level failure with no domain error behind it) and is always present.

Media typeapplication/json

The top-level response body. Wraps a non-empty list of [ErrorEntry].

object

errors

required

The error entries making up the envelope. Always non-empty.

Array<object>

One entry in the error envelope.

Carries a [Domain] naming the subsystem that produced it, an anchoring [ErrorScope], an optional target that disambiguates within the scope, a stable SCREAMING_SNAKE_CASE code, and a human-readable English message. See SPEC-DATA-0006 for the full envelope contract.

object

code

required

Machine-readable, stable, SCREAMING_SNAKE_CASE identifier.

string

domain

required

Which subsystem produced this entry. Always serialized.

One of:

string

data::error::DataError – record CRUD, validation, queries.

string

Allowed value: data

string

server::routes::metadata::error::MetadataError – the metadata write API (module/object/field/screen PUT and POST).

string

Allowed value: metadata

string

server::apply::ApplyError – the metadata apply/plan pipeline.

string

Allowed value: apply

string

server::git::GitError – the git-backed metadata repository.

string

Allowed value: git

string

auth::error::AuthError – JWT and credential authentication.

string

Allowed value: auth

string

server::routes::iam::error::IamError – principal and credential management (IAM handlers still emit Domain::Data for genuine request-body field validation, which stays DataError).

string

Allowed value: iam

string

server::routes::hfx::error::HfxError – HFX parse/emit.

string

Allowed value: hfx

string

Module packages (.hfmod, #1165): package format, signature and compatibility refusals, and the install lifecycle that consumes them.

string

Allowed value: module

string

A transport-level ApiError built directly (forbidden, not_found, internal, service_unavailable), with no <Domain>Error behind it.

string

Allowed value: api

location

Any of:

object

HFX source location for an HFX_PARSE entry.

Emitted as the extra location field on the entry JSON when present. The line/column are 1-based. The frame is the offending source line extracted verbatim from the input.

object

column

required

1-based column within the line, measured in UTF-16 code units of the prefix so browser-side editors can consume it directly.

integer format: uint32

frame

The offending source line text, when available.

string | null

line

required

1-based line number within the source text.

integer format: uint32

null

null

message

required

Server-authored English message. Not part of the API contract; may change across releases without notice.

string

rule

The key of the validation rule that failed, when the code is RULE_FAILED. None for all other codes. Skipped during serialization when absent so it does not appear on unrelated entries (same pattern as location).

string | null

scope

required

Anchoring category. Drives client-side rendering.

One of:

string

Attached to a specific request field. target is the field key.

string

Allowed value: field

string

Attached to the record being written or read. target is the id if known.

string

Allowed value: record

string

Attached to the request as a whole. target is always null.

string

Allowed value: global

target

Field key for field scope, record id for record scope, null otherwise. Always serialized, even when null.

string | null

Example

{
  "errors": [
    {
      "domain": "data",
      "scope": "field"
    }
  ]
}