Subject API

These operations create and manage pseudonymous subjects within the authenticated tenant and environment. Your backend resolves the subject from its own authenticated account mapping. Validate account ownership before accepting a subject identifier.

Create a subject with a stable external reference and the anchor established by your enrollment process. Begin an enrollment session through the session API and complete enrollment only after server readiness. Passkey registration uses a server-issued one-time grant. Revocation, recovery, adaptation freeze, export, and deletion are distinct lifecycle actions; choose the operation that matches your process.

Lifecycle constraints

The recovery policy controls the supported recovery path. Your application must establish the declared anchor and any required evidence reference through its own account-security process. GrayPass records the declared anchor; your account-security process establishes its provenance.

Record research consent separately from subject creation and ordinary product use. Deletion and revocation should also stop the customer's browser observer and update pending operations in the customer application.

Recording research consent returns the current Subject; the receipt is stored separately. Keep your own record of the person's choice and disclosure. Environment participation, current subject consent, per-frame opt-in and deployment eligibility all matter. Handle queued webhook deliveries and recipient copies through the separate delivery lifecycle described in Privacy.

Subject exports return up to 500 records per listed collection and up to 100 enrollments in one response. Use the export procedure to match these bounds to an individual request and arrange additional records. Coordinate financial, audit, and backup handling through the agreed privacy process.

Read Subject lifecycle and Privacy before implementing these operations. The operation contracts below specify fields, credential requirements, parameters, and responses.

GET /api/v1/subjects

Read a bounded list of non-deleted subjects visible in this environment.

Credential: Server credential.

Inputs: Optional limit defaults 100 and is bounded to 1-500; there is no cursor parameter.

Effect and retry behavior: Read-only. Deleted records are filtered, so the returned count may be below the limit.

Parameters

Name / location	Required	Meaning, type and constraints
`limit` (query)	No	Maximum records requested; default 100. The service bounds it to 1-500. No cursor pagination is exposed. integer default: `100`

Responses

HTTP status	Meaning	Body
`200`	Array of visible non-deleted subject records, up to the effective limit.	application/json: Array of `Subject`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Wrong credential scope or environment prevents access; an empty list is not evidence that another environment has no subjects.

Example

HTTP

GET /api/v1/subjects?limit=25

Response - HTTP 200:

[
  {
    "id": "sub_example",
    "environment": "env_example",
    "enrollment_state": "not_enrolled",
    "anchor": "customer_session",
    "recovery_policy": "re_enroll_with_anchor",
    "adaptation_frozen": true,
    "created_at": "2026-10-01T12:00:00Z",
    "revoked_at": null,
    "limitations": []
  }
]

POST /api/v1/subjects

Create the account-to-subject mapping in this environment, or return an existing subject with compatible security settings.

Credential: Server credential.

Inputs: Supply a stable external_ref. Stronger declared anchors require anchor_evidence_ref; only metadata.label is retained.

Effect and retry behavior: Stores a keyed reference and subject record. Identical reference/security settings return the existing subject; changed anchor or recovery policy conflicts.

Request body

application/json; required. SubjectCreate.

Responses

HTTP status	Meaning	Body
`201`	New or existing subject record with enrollment state and recovery settings.	application/json: `Subject`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 422 for missing required anchor evidence; 409 idempotency_conflict for a reference already bound to different security settings.

Example

HTTP

POST /api/v1/subjects

JSON request

{
  "external_ref": "account-42",
  "anchor": "customer_session",
  "recovery_policy": "re_enroll_with_anchor"
}

Response - HTTP 201:

{
  "id": "sub_example",
  "environment": "env_example",
  "enrollment_state": "not_enrolled",
  "anchor": "customer_session",
  "recovery_policy": "re_enroll_with_anchor",
  "adaptation_frozen": true,
  "created_at": "2026-10-01T12:00:00Z",
  "revoked_at": null,
  "limitations": []
}

DELETE /api/v1/subjects/{subject_id}

Delete the subject’s operational assurance data and make its record unavailable to normal subject lookup.

Credential: Server credential.

Inputs: Use the authenticated account’s subject id after confirming the intended deletion in your application.

Effect and retry behavior: Destructive lifecycle operation that invalidates usable assurance. Financial, audit and backup retention are separate; see privacy and subject lifecycle.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Responses

HTTP status	Meaning	Body
`204`	Operational deletion completed; the 204 response has no body.	No response body
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Reconcile state after an ambiguous response. A subsequent 404 can confirm completed deletion. Create a new subject only through an explicit application decision.

Example

HTTP

DELETE /api/v1/subjects/sub_example

HTTP 204; no response body.

GET /api/v1/subjects/{subject_id}

Retrieve the current subject enrollment and recovery state before starting a lifecycle operation.

Credential: Server credential.

Inputs: Use your stored subject identifier.

Effect and retry behavior: Read-only. Revoked records remain distinguishable from deleted or absent records.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Responses

HTTP status	Meaning	Body
`200`	Current subject state, declared anchor, recovery policy and limitations.	application/json: `Subject`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 404 for a missing, deleted or out-of-scope subject.

Example

HTTP

GET /api/v1/subjects/sub_example

Response - HTTP 200:

{
  "id": "sub_example",
  "environment": "env_example",
  "enrollment_state": "not_enrolled",
  "anchor": "customer_session",
  "recovery_policy": "re_enroll_with_anchor",
  "adaptation_frozen": true,
  "created_at": "2026-10-01T12:00:00Z",
  "revoked_at": null,
  "limitations": []
}

POST /api/v1/subjects/{subject_id}/adaptation/freeze

Ensure the subject’s existing template is not silently updated through online adaptation.

Credential: Server credential.

Inputs: Subject id only; no request body.

Effect and retry behavior: Sets adaptation_frozen to true while preserving the subject, template and evidence collection. Repeated freezing is safe. Use the dedicated revoke or delete operations for those lifecycle changes.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Responses

HTTP status	Meaning	Body
`200`	Subject record with adaptation_frozen true.	application/json: `Subject`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 404 for a missing or out-of-scope subject.

Example

HTTP

POST /api/v1/subjects/sub_example/adaptation/freeze

Response - HTTP 200:

{
  "id": "sub_example",
  "environment": "env_example",
  "enrollment_state": "not_enrolled",
  "anchor": "customer_session",
  "recovery_policy": "re_enroll_with_anchor",
  "adaptation_frozen": true,
  "created_at": "2026-10-01T12:00:00Z",
  "revoked_at": null,
  "limitations": []
}

POST /api/v1/subjects/{subject_id}/enrollments/complete

Create a Brainprint enrollment from the subject’s accepted enrollment-session evidence.

Credential: Server credential.

Inputs: Supply the owned enroll session after its evidence acknowledgement or status reports enrollment_ready=true. The server rechecks readiness at completion; accepted-window count, active seconds and modalities support progress reporting, not client-side thresholds. force defaults false.

Effect and retry behavior: Creates an enrollment attempt and may replace an existing template when force is true. Readiness requirements apply in both cases. Reconcile the subject state before retrying an uncertain response.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Request body

application/json; required. EnrollmentComplete.

Responses

HTTP status	Meaning	Body
`200`	Enrollment attempt status, accepted-window count and completion time.	application/json: `Enrollment`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 409 for revoked subjects or insufficient readiness; 404 for mismatched subject/session ownership or purpose. Inspect the returned enrollment status.

Example

HTTP

POST /api/v1/subjects/sub_example/enrollments/complete

JSON request

{
  "session": "ses_example",
  "force": false
}

Response - HTTP 200:

{
  "id": "enr_example",
  "subject": "sub_example",
  "status": "completed",
  "anchor": "customer_session",
  "windows_accepted": 5,
  "created_at": "2026-10-01T12:00:00Z",
  "completed_at": "2026-10-01T12:00:00Z",
  "limitations": []
}

POST /api/v1/subjects/{subject_id}/export

Retrieve a bounded subject-linked export containing lifecycle records and whether a Brainprint exists.

Credential: Server credential.

Inputs: Use the subject id. No body is required.

Effect and retry behavior: Read-only export; no template vector or passkey credential material is returned. Several collections stop at 500 records and there is no complete-history pagination protocol.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Responses

HTTP status	Meaning	Body
`200`	Bounded subject, Brainprint-presence, enrollment, authorization, session, passkey and consent records.	application/json: object
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 404 for an absent subject. Match the returned record bounds to the individual request and arrange additional history through the privacy process when needed.

Example

HTTP

POST /api/v1/subjects/sub_example/export

Response excerpt (selected fields) - HTTP 200:

{
  "subject": {
    "id": "sub_example"
  },
  "brainprint": {
    "present": false,
    "template_exported": false,
    "reason": "Templates are not exportable; they are deleted on request."
  },
  "sessions": [],
  "research_consents": []
}

POST /api/v1/subjects/{subject_id}/passkeys/register/complete

Verify the WebAuthn registration result and register the resulting credential for the subject.

Credential: Scoped browser token or server credential.

Inputs: Send registration_id from options.graypass_registration_id and credential as the browser’s complete serialized PublicKeyCredential attestation response. The example shows the outer container; use the SDK to supply the full WebAuthn fields within it.

Effect and retry behavior: Stores the verified passkey for subsequent action-bound challenge ceremonies. Request action approval through a challenge.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Request body

application/json; required. object.

Responses

HTTP status	Meaning	Body
`200`	Registered passkey id and creation time.	application/json: `PasskeyRegistered`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 422 when registration_id is absent; expired/mismatched ceremony, RP/origin, attestation or credential failures are refused.

Example

HTTP

POST /api/v1/subjects/sub_example/passkeys/register/complete

JSON request

{
  "registration_id": "pkr_example",
  "credential": {
    "id": "illustrative-credential-id",
    "type": "public-key"
  }
}

Response - HTTP 200:

{
  "id": "pky_example",
  "created_at": "2026-10-01T12:00:00Z"
}

POST /api/v1/subjects/{subject_id}/passkeys/register/options

Consume a server-issued registration grant and return WebAuthn creation options for that subject.

Credential: Scoped browser token or server credential.

Inputs: Send registration_grant obtained by the authenticated backend. A browser caller must also match subject and origin scope.

Effect and retry behavior: Consumes the grant and stores a registration ceremony. The response is the WebAuthn creation-options object with graypass_registration_id added. Preserve that id for completion and use the browser SDK for conversion.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Request body

application/json; required. PasskeyRegistrationOptionsRequest.

Responses

HTTP status	Meaning	Body
`200`	WebAuthn creation options with graypass_registration_id for the completion call.	application/json: object
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Expired, reused or mismatched grants and disallowed origins are refused. Request a new backend grant for a genuinely new ceremony.

Example

HTTP

POST /api/v1/subjects/sub_example/passkeys/register/options

JSON request

{
  "registration_grant": "illustrative-registration-grant-not-valid"
}

Response excerpt (selected fields) - HTTP 200:

{
  "graypass_registration_id": "pkr_example",
  "rp": {
    "name": "GrayPass"
  },
  "timeout": 60000
}

POST /api/v1/subjects/{subject_id}/passkeys/registration-grants

Authorize one subject-bound passkey registration ceremony from your authenticated backend.

Credential: Server credential.

Inputs: Subject id only. Obtain application consent and validate account ownership before issuing the grant.

Effect and retry behavior: Issues an expiring one-time grant. It is consumed when registration options are requested; a retry may create a separate grant.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Responses

HTTP status	Meaning	Body
`201`	One-time registration token and ISO 8601 expiry.	application/json: `PasskeyRegistrationGrant`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Proceed with registration after subject lifecycle and scope checks pass and the grant is stored successfully.

Example

HTTP

POST /api/v1/subjects/sub_example/passkeys/registration-grants

Response excerpt (selected fields) - HTTP 201:

{
  "expires_at": "2026-10-01T12:05:00Z"
}

DELETE /api/v1/subjects/{subject_id}/passkeys/{passkey_id}

Remove a subject passkey from eligibility for future GrayPass action challenges.

Credential: Server credential.

Inputs: Provide the owning subject id and registered passkey id.

Effect and retry behavior: Revokes the credential within GrayPass. Authenticator removal and subject recovery follow their separate lifecycle procedures.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string
`passkey_id` (path)	Yes	Identifier of the subject’s registered passkey to revoke. string

Responses

HTTP status	Meaning	Body
`204`	Passkey revocation completed; the 204 response has no body.	No response body
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Missing, out-of-scope or mismatched subject/passkey records are refused.

Example

HTTP

DELETE /api/v1/subjects/sub_example/passkeys/pky_example

HTTP 204; no response body.

POST /api/v1/subjects/{subject_id}/recovery

Move a revoked subject into the permitted re-enrollment path after your application establishes the required anchor.

Credential: Server credential.

Inputs: Specify the supported anchor and required anchor_evidence_ref. The subject’s stored recovery policy controls eligibility.

Effect and retry behavior: Begins a fresh enrollment lifecycle. Complete enrollment to create a new template, then authorize subsequent actions separately.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Request body

application/json; required. RecoveryBegin.

Responses

HTTP status	Meaning	Body
`200`	Subject reset to not_enrolled under the accepted replacement anchor.	application/json: `Subject`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 409 when the subject is not revoked or its policy requires manual review; 422 when required anchor evidence is absent.

Example

HTTP

POST /api/v1/subjects/sub_example/recovery

JSON request

{
  "anchor": "customer_session"
}

Response - HTTP 200:

{
  "id": "sub_example",
  "environment": "env_example",
  "enrollment_state": "not_enrolled",
  "anchor": "customer_session",
  "recovery_policy": "re_enroll_with_anchor",
  "adaptation_frozen": true,
  "created_at": "2026-10-01T12:00:00Z",
  "revoked_at": null,
  "limitations": []
}

Record a separate, attributed subject decision about behavioral-model research participation.

Credential: Server credential.

Inputs: consented must be a JSON boolean. The API fixes purpose behavioral_model_research and disclosure version research-consent/1.

Effect and retry behavior: Appends a granted or revoked consent receipt; repeated calls append receipts. Research retention also requires environment participation, per-frame opt-in and deployment eligibility.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Request body

application/json; required. ResearchConsentRequest.

Responses

HTTP status	Meaning	Body
`200`	Current subject record. The consent receipt is stored separately; session research eligibility is reported when creating a session.	application/json: `Subject`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 404 for an unavailable subject; 422 for a non-boolean value. Research collection also requires deployment and environment enablement and per-frame opt-in.

Example

HTTP

POST /api/v1/subjects/sub_example/research-consent

JSON request

{
  "consented": false
}

Response - HTTP 200:

{
  "id": "sub_example",
  "environment": "env_example",
  "enrollment_state": "not_enrolled",
  "anchor": "customer_session",
  "recovery_policy": "re_enroll_with_anchor",
  "adaptation_frozen": true,
  "created_at": "2026-10-01T12:00:00Z",
  "revoked_at": null,
  "limitations": []
}

POST /api/v1/subjects/{subject_id}/revoke

Revoke the subject’s existing assurance and terminate its usable session and proof capabilities.

Credential: Server credential.

Inputs: Use the subject selected through your authenticated account-security workflow.

Effect and retry behavior: Changes enrollment state to revoked, removes usable template assurance and invalidates associated sessions and proofs. Stop the observer in your application too.

Parameters

Name / location	Required	Meaning, type and constraints
`subject_id` (path)	Yes	Subject identifier resolved from your authenticated account mapping. string

Responses

HTTP status	Meaning	Body
`200`	Subject record reflecting revoked enrollment state and revocation time.	application/json: `Subject`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Missing or out-of-scope subjects fail. Resolve any ambiguous response by reading lifecycle state before initiating recovery.

Example

HTTP

POST /api/v1/subjects/sub_example/revoke

Response - HTTP 200:

{
  "id": "sub_example",
  "environment": "env_example",
  "enrollment_state": "revoked",
  "anchor": "customer_session",
  "recovery_policy": "re_enroll_with_anchor",
  "adaptation_frozen": true,
  "created_at": "2026-10-01T12:00:00Z",
  "revoked_at": "2026-10-01T12:00:00Z",
  "limitations": []
}

Subject API

Lifecycle constraints

GET /api/v1/subjects

Parameters

Responses

Example

POST /api/v1/subjects

Request body

Responses

Example

DELETE /api/v1/subjects/{subject_id}

Parameters

Responses

Example

GET /api/v1/subjects/{subject_id}

Parameters

Responses

Example

POST /api/v1/subjects/{subject_id}/adaptation/freeze

Parameters

Responses

Example

POST /api/v1/subjects/{subject_id}/enrollments/complete

Parameters

Request body

Responses

Example

POST /api/v1/subjects/{subject_id}/export

Parameters

Responses

Example

POST /api/v1/subjects/{subject_id}/passkeys/register/complete

Parameters

Request body

Responses

Example

POST /api/v1/subjects/{subject_id}/passkeys/register/options

Parameters

Request body

Responses

Example

POST /api/v1/subjects/{subject_id}/passkeys/registration-grants

Parameters

Responses

Example

DELETE /api/v1/subjects/{subject_id}/passkeys/{passkey_id}

Parameters

Responses

Example

POST /api/v1/subjects/{subject_id}/recovery

Parameters

Request body

Responses

Example

POST /api/v1/subjects/{subject_id}/research-consent

Parameters

Request body

Responses

Example

POST /api/v1/subjects/{subject_id}/revoke

Parameters

Responses

Example