Package ai.vectros.resources.auth

Class AsyncAuthClient

java.lang.Object
ai.vectros.resources.auth.AsyncAuthClient
public class AsyncAuthClient extends Object

  • Field Details

  • Constructor Details

    • AsyncAuthClient

      public AsyncAuthClient(ClientOptions clientOptions)

  • Method Details

    • withRawResponse

      public AsyncRawAuthClient withRawResponse()
      Get responses with HTTP metadata like headers

    • getJwks

      public CompletableFuture<JwksResponse> getJwks()
      Returns the platform's JWT signing public key in RFC 7517 JWKS format. Use it with any JWKS-aware JWT library to verify inv_* invite tokens, st_* scoped tokens, and other platform-signed tokens locally, without calling back to the API for each verification. The response carries a one-hour Cache-Control, so cache it and re-fetch roughly hourly rather than on every verification. The kid value changes when the key rotates; re-fetch this document whenever you encounter a token signed with an unknown kid.

    • getJwks

      public CompletableFuture<JwksResponse> getJwks(RequestOptions requestOptions)
      Returns the platform's JWT signing public key in RFC 7517 JWKS format. Use it with any JWKS-aware JWT library to verify inv_* invite tokens, st_* scoped tokens, and other platform-signed tokens locally, without calling back to the API for each verification. The response carries a one-hour Cache-Control, so cache it and re-fetch roughly hourly rather than on every verification. The kid value changes when the key rotates; re-fetch this document whenever you encounter a token signed with an unknown kid.

    • getAccessLog

      public CompletableFuture<ReadAccessLogPage> getAccessLog()
      Returns a page of per-subject PHI read-access rows: who read which subject's PHI, when, against which record, and whether any sensitive value was actually revealed in plaintext. Metadata only — never the PHI itself. This is the disclosure-accounting surface from which a covered entity derives its HIPAA §164.528 accounting of disclosures. Provide at least one query axis: a subject (subjectType + subjectId) within a contextId for the primary accounting query; resourceId within a contextId for 'who read this record'; callerKeyId for 'what did this credential read' (account-wide forensic); or contextId alone to enumerate a whole context. from/to bound the time window. Results are scoped to your account, derived from your token — never from input. Requires the access-log:r scope.

    • getAccessLog

      public CompletableFuture<ReadAccessLogPage> getAccessLog(RequestOptions requestOptions)
      Returns a page of per-subject PHI read-access rows: who read which subject's PHI, when, against which record, and whether any sensitive value was actually revealed in plaintext. Metadata only — never the PHI itself. This is the disclosure-accounting surface from which a covered entity derives its HIPAA §164.528 accounting of disclosures. Provide at least one query axis: a subject (subjectType + subjectId) within a contextId for the primary accounting query; resourceId within a contextId for 'who read this record'; callerKeyId for 'what did this credential read' (account-wide forensic); or contextId alone to enumerate a whole context. from/to bound the time window. Results are scoped to your account, derived from your token — never from input. Requires the access-log:r scope.

    • getAccessLog

      public CompletableFuture<ReadAccessLogPage> getAccessLog(GetAccessLogRequest request)
      Returns a page of per-subject PHI read-access rows: who read which subject's PHI, when, against which record, and whether any sensitive value was actually revealed in plaintext. Metadata only — never the PHI itself. This is the disclosure-accounting surface from which a covered entity derives its HIPAA §164.528 accounting of disclosures. Provide at least one query axis: a subject (subjectType + subjectId) within a contextId for the primary accounting query; resourceId within a contextId for 'who read this record'; callerKeyId for 'what did this credential read' (account-wide forensic); or contextId alone to enumerate a whole context. from/to bound the time window. Results are scoped to your account, derived from your token — never from input. Requires the access-log:r scope.

    • getAccessLog

      public CompletableFuture<ReadAccessLogPage> getAccessLog(GetAccessLogRequest request, RequestOptions requestOptions)
      Returns a page of per-subject PHI read-access rows: who read which subject's PHI, when, against which record, and whether any sensitive value was actually revealed in plaintext. Metadata only — never the PHI itself. This is the disclosure-accounting surface from which a covered entity derives its HIPAA §164.528 accounting of disclosures. Provide at least one query axis: a subject (subjectType + subjectId) within a contextId for the primary accounting query; resourceId within a contextId for 'who read this record'; callerKeyId for 'what did this credential read' (account-wide forensic); or contextId alone to enumerate a whole context. from/to bound the time window. Results are scoped to your account, derived from your token — never from input. Requires the access-log:r scope.

    • listScopedKeys

      public CompletableFuture<ScopedKeyPage> listScopedKeys()
      Lists your scoped API keys (ssk_*) in your credential's own environment — a live key lists live keys, a test key lists test keys. Revoked keys are excluded. Requires the keys:r scope.

    • listScopedKeys

      public CompletableFuture<ScopedKeyPage> listScopedKeys(RequestOptions requestOptions)
      Lists your scoped API keys (ssk_*) in your credential's own environment — a live key lists live keys, a test key lists test keys. Revoked keys are excluded. Requires the keys:r scope.

    • createScopedKey

      public CompletableFuture<ScopedKeyResponse> createScopedKey(CreateScopedKeyRequest request)
      Creates a scoped API key (an ssk_* secret) that inherits its permissions from an existing access profile in your account. The call is idempotent on the combination of tenant, context, user, and key name: re-issuing the same request returns the existing key WITHOUT re-disclosing its raw secret. The raw key is returned ONLY in this response — store it securely, as it cannot be retrieved again. Requires the keys:c scope. If you use a scoped credential, keys:c alone is not sufficient: because the minted key is durably bound to the profile you name, the profile's effective scopes may not exceed your own, and you may only mint against a profile whose identityOverrides values your own identity holds. Minting a key bound to your OWN principal needs nothing further; minting one bound to a DIFFERENT principal additionally requires the delegate-mint capability (granted_capabilities) on your credential — without it the request is refused. A root API key (sk_) is exempt from all three bounds.

    • createScopedKey

      public CompletableFuture<ScopedKeyResponse> createScopedKey(CreateScopedKeyRequest request, RequestOptions requestOptions)
      Creates a scoped API key (an ssk_* secret) that inherits its permissions from an existing access profile in your account. The call is idempotent on the combination of tenant, context, user, and key name: re-issuing the same request returns the existing key WITHOUT re-disclosing its raw secret. The raw key is returned ONLY in this response — store it securely, as it cannot be retrieved again. Requires the keys:c scope. If you use a scoped credential, keys:c alone is not sufficient: because the minted key is durably bound to the profile you name, the profile's effective scopes may not exceed your own, and you may only mint against a profile whose identityOverrides values your own identity holds. Minting a key bound to your OWN principal needs nothing further; minting one bound to a DIFFERENT principal additionally requires the delegate-mint capability (granted_capabilities) on your credential — without it the request is refused. A root API key (sk_) is exempt from all three bounds.

    • getScopedKey

      public CompletableFuture<ScopedKeyResponse> getScopedKey(String keyId)
      Returns the metadata for a single scoped API key. The raw secret is NOT included — it is only ever returned once, when the key is first created. Requires the keys:r scope.

    • getScopedKey

      public CompletableFuture<ScopedKeyResponse> getScopedKey(String keyId, RequestOptions requestOptions)
      Returns the metadata for a single scoped API key. The raw secret is NOT included — it is only ever returned once, when the key is first created. Requires the keys:r scope.

    • getScopedKey

      public CompletableFuture<ScopedKeyResponse> getScopedKey(String keyId, GetScopedKeyRequest request)
      Returns the metadata for a single scoped API key. The raw secret is NOT included — it is only ever returned once, when the key is first created. Requires the keys:r scope.

    • getScopedKey

      public CompletableFuture<ScopedKeyResponse> getScopedKey(String keyId, GetScopedKeyRequest request, RequestOptions requestOptions)
      Returns the metadata for a single scoped API key. The raw secret is NOT included — it is only ever returned once, when the key is first created. Requires the keys:r scope.

    • revokeScopedKey

      public CompletableFuture<Void> revokeScopedKey(String keyId)
      Revokes a scoped API key. Its status changes to revoked and it stops working within about 5 minutes, the maximum time authorization is cached. Revocation is permanent. Requires the keys:d scope.

    • revokeScopedKey

      public CompletableFuture<Void> revokeScopedKey(String keyId, RequestOptions requestOptions)
      Revokes a scoped API key. Its status changes to revoked and it stops working within about 5 minutes, the maximum time authorization is cached. Revocation is permanent. Requires the keys:d scope.

    • revokeScopedKey

      public CompletableFuture<Void> revokeScopedKey(String keyId, RevokeScopedKeyRequest request)
      Revokes a scoped API key. Its status changes to revoked and it stops working within about 5 minutes, the maximum time authorization is cached. Revocation is permanent. Requires the keys:d scope.

    • revokeScopedKey

      public CompletableFuture<Void> revokeScopedKey(String keyId, RevokeScopedKeyRequest request, RequestOptions requestOptions)
      Revokes a scoped API key. Its status changes to revoked and it stops working within about 5 minutes, the maximum time authorization is cached. Revocation is permanent. Requires the keys:d scope.

    • getAdminLogs

      public CompletableFuture<AdminLogsResponse> getAdminLogs(GetAdminLogsRequest request)
      Returns recent API call logs for your account. Each entry represents one API request; request and response bodies are never logged. startTime and endTime must be ISO-8601 UTC (e.g. 2025-01-15T09:00:00Z); endTime defaults to now. Filter by resource, method, key id, or context id, or set errorsOnly to see only failures. Results are scoped to your account, derived from your token — never from input. Requires the logs:r scope.

    • getAdminLogs

      public CompletableFuture<AdminLogsResponse> getAdminLogs(GetAdminLogsRequest request, RequestOptions requestOptions)
      Returns recent API call logs for your account. Each entry represents one API request; request and response bodies are never logged. startTime and endTime must be ISO-8601 UTC (e.g. 2025-01-15T09:00:00Z); endTime defaults to now. Filter by resource, method, key id, or context id, or set errorsOnly to see only failures. Results are scoped to your account, derived from your token — never from input. Requires the logs:r scope.

    • listAccessProfiles

      public CompletableFuture<AccessProfilePage> listAccessProfiles(String contextId)
      Returns the access profiles assigned within the given app context — in effect, who has access to this context and with what scopes. Each profile binds a principal to either a set of inline scopes or a referenced role. Results are paginated. Requires the profiles:r scope.

    • listAccessProfiles

      public CompletableFuture<AccessProfilePage> listAccessProfiles(String contextId, RequestOptions requestOptions)
      Returns the access profiles assigned within the given app context — in effect, who has access to this context and with what scopes. Each profile binds a principal to either a set of inline scopes or a referenced role. Results are paginated. Requires the profiles:r scope.

    • listAccessProfiles

      public CompletableFuture<AccessProfilePage> listAccessProfiles(String contextId, ListAccessProfilesRequest request)
      Returns the access profiles assigned within the given app context — in effect, who has access to this context and with what scopes. Each profile binds a principal to either a set of inline scopes or a referenced role. Results are paginated. Requires the profiles:r scope.

    • listAccessProfiles

      public CompletableFuture<AccessProfilePage> listAccessProfiles(String contextId, ListAccessProfilesRequest request, RequestOptions requestOptions)
      Returns the access profiles assigned within the given app context — in effect, who has access to this context and with what scopes. Each profile binds a principal to either a set of inline scopes or a referenced role. Results are paginated. Requires the profiles:r scope.

    • createAccessProfile

      public CompletableFuture<AccessProfileResponse> createAccessProfile(String contextId, AccessProfileRequest body)
      Creates a new access profile under the given app context. This call is idempotent by principalId: if a profile with the same principalId already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's scopes/roleId, identityOverrides, and status instead of returning it unchanged, set ?upsert=true (this also requires the profiles:u scope, and applies the same identityOverrides bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). The principalId must name a principal that already exists: a usr_ principal must be a live user in your tenant, so create the user before granting it a profile. A usr_ id that names no such user is rejected, and no profile is created. key_ principals are not checked this way. You must provide exactly one of scopes (an inline list of scopes) or roleId (a reference to a role); supplying both, or neither, is rejected. identityOverrides is keyed by ownership namespace in scope:<namespace> form — scope:org and scope:client for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or userId) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:c scope.

    • createAccessProfile

      public CompletableFuture<AccessProfileResponse> createAccessProfile(String contextId, AccessProfileRequest body, RequestOptions requestOptions)
      Creates a new access profile under the given app context. This call is idempotent by principalId: if a profile with the same principalId already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's scopes/roleId, identityOverrides, and status instead of returning it unchanged, set ?upsert=true (this also requires the profiles:u scope, and applies the same identityOverrides bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). The principalId must name a principal that already exists: a usr_ principal must be a live user in your tenant, so create the user before granting it a profile. A usr_ id that names no such user is rejected, and no profile is created. key_ principals are not checked this way. You must provide exactly one of scopes (an inline list of scopes) or roleId (a reference to a role); supplying both, or neither, is rejected. identityOverrides is keyed by ownership namespace in scope:<namespace> form — scope:org and scope:client for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or userId) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:c scope.

    • createAccessProfile

      public CompletableFuture<AccessProfileResponse> createAccessProfile(String contextId, CreateAccessProfileRequest request)
      Creates a new access profile under the given app context. This call is idempotent by principalId: if a profile with the same principalId already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's scopes/roleId, identityOverrides, and status instead of returning it unchanged, set ?upsert=true (this also requires the profiles:u scope, and applies the same identityOverrides bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). The principalId must name a principal that already exists: a usr_ principal must be a live user in your tenant, so create the user before granting it a profile. A usr_ id that names no such user is rejected, and no profile is created. key_ principals are not checked this way. You must provide exactly one of scopes (an inline list of scopes) or roleId (a reference to a role); supplying both, or neither, is rejected. identityOverrides is keyed by ownership namespace in scope:<namespace> form — scope:org and scope:client for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or userId) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:c scope.

    • createAccessProfile

      public CompletableFuture<AccessProfileResponse> createAccessProfile(String contextId, CreateAccessProfileRequest request, RequestOptions requestOptions)
      Creates a new access profile under the given app context. This call is idempotent by principalId: if a profile with the same principalId already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's scopes/roleId, identityOverrides, and status instead of returning it unchanged, set ?upsert=true (this also requires the profiles:u scope, and applies the same identityOverrides bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). The principalId must name a principal that already exists: a usr_ principal must be a live user in your tenant, so create the user before granting it a profile. A usr_ id that names no such user is rejected, and no profile is created. key_ principals are not checked this way. You must provide exactly one of scopes (an inline list of scopes) or roleId (a reference to a role); supplying both, or neither, is rejected. identityOverrides is keyed by ownership namespace in scope:<namespace> form — scope:org and scope:client for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or userId) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:c scope.

    • listAppContexts

      public CompletableFuture<AppContextPage> listAppContexts()
      Returns a paginated list of the app contexts in your account. Each app context is a namespace that groups the access profiles and roles for one of your applications. Requires the app-contexts:r scope.

    • listAppContexts

      public CompletableFuture<AppContextPage> listAppContexts(RequestOptions requestOptions)
      Returns a paginated list of the app contexts in your account. Each app context is a namespace that groups the access profiles and roles for one of your applications. Requires the app-contexts:r scope.

    • listAppContexts

      public CompletableFuture<AppContextPage> listAppContexts(ListAppContextsRequest request)
      Returns a paginated list of the app contexts in your account. Each app context is a namespace that groups the access profiles and roles for one of your applications. Requires the app-contexts:r scope.

    • listAppContexts

      public CompletableFuture<AppContextPage> listAppContexts(ListAppContextsRequest request, RequestOptions requestOptions)
      Returns a paginated list of the app contexts in your account. Each app context is a namespace that groups the access profiles and roles for one of your applications. Requires the app-contexts:r scope.

    • createAppContext

      public CompletableFuture<AppContextResponse> createAppContext(AppContextRequest body)
      Creates a new app context. This call is idempotent by contextId: if an app context with the same contextId already exists, the existing app context is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing context was returned) tells the two apart. To overwrite an existing context's name/description/companyName instead of returning it unchanged, set ?upsert=true (this also requires the app-contexts:u scope). The reserved contextId value vectros-admin cannot be created through this endpoint; it is provisioned automatically for your account. Requires the app-contexts:c scope.

    • createAppContext

      public CompletableFuture<AppContextResponse> createAppContext(AppContextRequest body, RequestOptions requestOptions)
      Creates a new app context. This call is idempotent by contextId: if an app context with the same contextId already exists, the existing app context is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing context was returned) tells the two apart. To overwrite an existing context's name/description/companyName instead of returning it unchanged, set ?upsert=true (this also requires the app-contexts:u scope). The reserved contextId value vectros-admin cannot be created through this endpoint; it is provisioned automatically for your account. Requires the app-contexts:c scope.

    • createAppContext

      public CompletableFuture<AppContextResponse> createAppContext(CreateAppContextRequest request)
      Creates a new app context. This call is idempotent by contextId: if an app context with the same contextId already exists, the existing app context is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing context was returned) tells the two apart. To overwrite an existing context's name/description/companyName instead of returning it unchanged, set ?upsert=true (this also requires the app-contexts:u scope). The reserved contextId value vectros-admin cannot be created through this endpoint; it is provisioned automatically for your account. Requires the app-contexts:c scope.

    • createAppContext

      public CompletableFuture<AppContextResponse> createAppContext(CreateAppContextRequest request, RequestOptions requestOptions)
      Creates a new app context. This call is idempotent by contextId: if an app context with the same contextId already exists, the existing app context is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing context was returned) tells the two apart. To overwrite an existing context's name/description/companyName instead of returning it unchanged, set ?upsert=true (this also requires the app-contexts:u scope). The reserved contextId value vectros-admin cannot be created through this endpoint; it is provisioned automatically for your account. Requires the app-contexts:c scope.

    • listRoles

      public CompletableFuture<RolePage> listRoles(String contextId)
      Returns the roles defined under the given app context. A role is a reusable, named bundle of scopes that access profiles can reference instead of listing scopes inline. Results are paginated. Requires the profiles:r scope.

    • listRoles

      public CompletableFuture<RolePage> listRoles(String contextId, RequestOptions requestOptions)
      Returns the roles defined under the given app context. A role is a reusable, named bundle of scopes that access profiles can reference instead of listing scopes inline. Results are paginated. Requires the profiles:r scope.

    • listRoles

      public CompletableFuture<RolePage> listRoles(String contextId, ListRolesRequest request)
      Returns the roles defined under the given app context. A role is a reusable, named bundle of scopes that access profiles can reference instead of listing scopes inline. Results are paginated. Requires the profiles:r scope.

    • listRoles

      public CompletableFuture<RolePage> listRoles(String contextId, ListRolesRequest request, RequestOptions requestOptions)
      Returns the roles defined under the given app context. A role is a reusable, named bundle of scopes that access profiles can reference instead of listing scopes inline. Results are paginated. Requires the profiles:r scope.

    • createRole

      public CompletableFuture<RoleResponse> createRole(String contextId, RoleRequest body)
      Creates a new role under the given app context. This call is idempotent by roleId: if a role with the same roleId already exists, the existing role is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing role was returned) tells the two apart. To overwrite an existing role's name/description/scopes instead of returning it unchanged, set ?upsert=true (this also requires the profiles:u scope). If you use a scoped credential, the role's scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:c scope.

    • createRole

      public CompletableFuture<RoleResponse> createRole(String contextId, RoleRequest body, RequestOptions requestOptions)
      Creates a new role under the given app context. This call is idempotent by roleId: if a role with the same roleId already exists, the existing role is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing role was returned) tells the two apart. To overwrite an existing role's name/description/scopes instead of returning it unchanged, set ?upsert=true (this also requires the profiles:u scope). If you use a scoped credential, the role's scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:c scope.

    • createRole

      public CompletableFuture<RoleResponse> createRole(String contextId, CreateRoleRequest request)
      Creates a new role under the given app context. This call is idempotent by roleId: if a role with the same roleId already exists, the existing role is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing role was returned) tells the two apart. To overwrite an existing role's name/description/scopes instead of returning it unchanged, set ?upsert=true (this also requires the profiles:u scope). If you use a scoped credential, the role's scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:c scope.

    • createRole

      public CompletableFuture<RoleResponse> createRole(String contextId, CreateRoleRequest request, RequestOptions requestOptions)
      Creates a new role under the given app context. This call is idempotent by roleId: if a role with the same roleId already exists, the existing role is returned (with status 200) instead of creating a duplicate. The response's created field (and the HTTP status — 201 when created, 200 when an existing role was returned) tells the two apart. To overwrite an existing role's name/description/scopes instead of returning it unchanged, set ?upsert=true (this also requires the profiles:u scope). If you use a scoped credential, the role's scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:c scope.

    • getAccessProfile

      public CompletableFuture<AccessProfileResponse> getAccessProfile(String contextId, String principalId)
      Returns a single access profile by its principalId within the given app context. Requires the profiles:r scope.

    • getAccessProfile

      public CompletableFuture<AccessProfileResponse> getAccessProfile(String contextId, String principalId, RequestOptions requestOptions)
      Returns a single access profile by its principalId within the given app context. Requires the profiles:r scope.

    • getAccessProfile

      public CompletableFuture<AccessProfileResponse> getAccessProfile(String contextId, String principalId, GetAccessProfileRequest request)
      Returns a single access profile by its principalId within the given app context. Requires the profiles:r scope.

    • getAccessProfile

      public CompletableFuture<AccessProfileResponse> getAccessProfile(String contextId, String principalId, GetAccessProfileRequest request, RequestOptions requestOptions)
      Returns a single access profile by its principalId within the given app context. Requires the profiles:r scope.

    • updateAccessProfile

      public CompletableFuture<AccessProfileResponse> updateAccessProfile(String contextId, String principalId, UpdateAccessProfileRequest request)
      Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline scopes or a roleId, never both — so setting scopes clears any roleId, and setting roleId clears any inline scopes. The contextId and principalId are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own, and its identityOverrides are bounded twice: you may only set a value your own identity holds, and you may only change or clear a value the profile already holds if that value is yours as well. Repointing or clearing another principal's established identity therefore returns 403. A root API key (sk_) is exempt. If you set roleId, it must reference a role that already exists in this context. Requires the profiles:u scope.

    • updateAccessProfile

      public CompletableFuture<AccessProfileResponse> updateAccessProfile(String contextId, String principalId, UpdateAccessProfileRequest request, RequestOptions requestOptions)
      Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline scopes or a roleId, never both — so setting scopes clears any roleId, and setting roleId clears any inline scopes. The contextId and principalId are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own, and its identityOverrides are bounded twice: you may only set a value your own identity holds, and you may only change or clear a value the profile already holds if that value is yours as well. Repointing or clearing another principal's established identity therefore returns 403. A root API key (sk_) is exempt. If you set roleId, it must reference a role that already exists in this context. Requires the profiles:u scope.

    • deleteAccessProfile

      public CompletableFuture<Void> deleteAccessProfile(String contextId, String principalId)
      Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. If you use a scoped credential and the profile carries identityOverrides, you may only delete it when you hold those values yourself — deleting a profile removes its identity, so the same bound applies as when clearing it. A profile with no identityOverrides is unaffected, and a root API key (sk_) is exempt. Requires the profiles:d scope.

    • deleteAccessProfile

      public CompletableFuture<Void> deleteAccessProfile(String contextId, String principalId, RequestOptions requestOptions)
      Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. If you use a scoped credential and the profile carries identityOverrides, you may only delete it when you hold those values yourself — deleting a profile removes its identity, so the same bound applies as when clearing it. A profile with no identityOverrides is unaffected, and a root API key (sk_) is exempt. Requires the profiles:d scope.

    • deleteAccessProfile

      public CompletableFuture<Void> deleteAccessProfile(String contextId, String principalId, DeleteAccessProfileRequest request)
      Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. If you use a scoped credential and the profile carries identityOverrides, you may only delete it when you hold those values yourself — deleting a profile removes its identity, so the same bound applies as when clearing it. A profile with no identityOverrides is unaffected, and a root API key (sk_) is exempt. Requires the profiles:d scope.

    • deleteAccessProfile

      public CompletableFuture<Void> deleteAccessProfile(String contextId, String principalId, DeleteAccessProfileRequest request, RequestOptions requestOptions)
      Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. If you use a scoped credential and the profile carries identityOverrides, you may only delete it when you hold those values yourself — deleting a profile removes its identity, so the same bound applies as when clearing it. A profile with no identityOverrides is unaffected, and a root API key (sk_) is exempt. Requires the profiles:d scope.

    • getAppContext

      public CompletableFuture<AppContextResponse> getAppContext(String contextId)
      Returns a single app context by its contextId. Requires the app-contexts:r scope.

    • getAppContext

      public CompletableFuture<AppContextResponse> getAppContext(String contextId, RequestOptions requestOptions)
      Returns a single app context by its contextId. Requires the app-contexts:r scope.

    • getAppContext

      public CompletableFuture<AppContextResponse> getAppContext(String contextId, GetAppContextRequest request)
      Returns a single app context by its contextId. Requires the app-contexts:r scope.

    • getAppContext

      public CompletableFuture<AppContextResponse> getAppContext(String contextId, GetAppContextRequest request, RequestOptions requestOptions)
      Returns a single app context by its contextId. Requires the app-contexts:r scope.

    • updateAppContext

      public CompletableFuture<AppContextResponse> updateAppContext(String contextId, UpdateAppContextRequest request)
      Updates the name, description, and/or companyName of an app context. This is a partial update: any field you omit (or send as null) keeps its existing value. The contextId is immutable and is taken from the URL path, so any contextId in the request body is ignored. Requires the app-contexts:u scope.

    • updateAppContext

      public CompletableFuture<AppContextResponse> updateAppContext(String contextId, UpdateAppContextRequest request, RequestOptions requestOptions)
      Updates the name, description, and/or companyName of an app context. This is a partial update: any field you omit (or send as null) keeps its existing value. The contextId is immutable and is taken from the URL path, so any contextId in the request body is ignored. Requires the app-contexts:u scope.

    • deleteAppContext

      public CompletableFuture<Void> deleteAppContext(String contextId)
      Permanently deletes an app context and everything in it — every record, document, folder, schema, role, and access profile belonging to the context. This is irreversible. The deletion runs asynchronously: the call returns 202 immediately and the context's data drains in the background. Poll the context's status field to observe when the teardown completes (purging while draining, then deleted). To guard against accidental deletion, you must echo the contextId back in the confirm query parameter (?confirm={contextId}). The reserved default and vectros-admin contexts cannot be deleted. This operation requires a root API key (one beginning with sk_): no scoped credential, not even one with full wildcard (*) scope, can trigger this teardown.

    • deleteAppContext

      public CompletableFuture<Void> deleteAppContext(String contextId, RequestOptions requestOptions)
      Permanently deletes an app context and everything in it — every record, document, folder, schema, role, and access profile belonging to the context. This is irreversible. The deletion runs asynchronously: the call returns 202 immediately and the context's data drains in the background. Poll the context's status field to observe when the teardown completes (purging while draining, then deleted). To guard against accidental deletion, you must echo the contextId back in the confirm query parameter (?confirm={contextId}). The reserved default and vectros-admin contexts cannot be deleted. This operation requires a root API key (one beginning with sk_): no scoped credential, not even one with full wildcard (*) scope, can trigger this teardown.

    • deleteAppContext

      public CompletableFuture<Void> deleteAppContext(String contextId, DeleteAppContextRequest request)
      Permanently deletes an app context and everything in it — every record, document, folder, schema, role, and access profile belonging to the context. This is irreversible. The deletion runs asynchronously: the call returns 202 immediately and the context's data drains in the background. Poll the context's status field to observe when the teardown completes (purging while draining, then deleted). To guard against accidental deletion, you must echo the contextId back in the confirm query parameter (?confirm={contextId}). The reserved default and vectros-admin contexts cannot be deleted. This operation requires a root API key (one beginning with sk_): no scoped credential, not even one with full wildcard (*) scope, can trigger this teardown.

    • deleteAppContext

      public CompletableFuture<Void> deleteAppContext(String contextId, DeleteAppContextRequest request, RequestOptions requestOptions)
      Permanently deletes an app context and everything in it — every record, document, folder, schema, role, and access profile belonging to the context. This is irreversible. The deletion runs asynchronously: the call returns 202 immediately and the context's data drains in the background. Poll the context's status field to observe when the teardown completes (purging while draining, then deleted). To guard against accidental deletion, you must echo the contextId back in the confirm query parameter (?confirm={contextId}). The reserved default and vectros-admin contexts cannot be deleted. This operation requires a root API key (one beginning with sk_): no scoped credential, not even one with full wildcard (*) scope, can trigger this teardown.

    • getRole

      public CompletableFuture<RoleResponse> getRole(String contextId, String roleId)
      Returns a single role by its roleId within the given app context. Requires the profiles:r scope.

    • getRole

      public CompletableFuture<RoleResponse> getRole(String contextId, String roleId, RequestOptions requestOptions)
      Returns a single role by its roleId within the given app context. Requires the profiles:r scope.

    • getRole

      public CompletableFuture<RoleResponse> getRole(String contextId, String roleId, GetRoleRequest request)
      Returns a single role by its roleId within the given app context. Requires the profiles:r scope.

    • getRole

      public CompletableFuture<RoleResponse> getRole(String contextId, String roleId, GetRoleRequest request, RequestOptions requestOptions)
      Returns a single role by its roleId within the given app context. Requires the profiles:r scope.

    • updateRole

      public CompletableFuture<RoleResponse> updateRole(String contextId, String roleId, UpdateRoleRequest request)
      Updates a role. This is a partial update: any field you omit (or send as null) keeps its existing value. The roleId and contextId are immutable. Scope changes take effect for access profiles that reference this role within about five minutes. If you use a scoped credential, the role's scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:u scope.

    • updateRole

      public CompletableFuture<RoleResponse> updateRole(String contextId, String roleId, UpdateRoleRequest request, RequestOptions requestOptions)
      Updates a role. This is a partial update: any field you omit (or send as null) keeps its existing value. The roleId and contextId are immutable. Scope changes take effect for access profiles that reference this role within about five minutes. If you use a scoped credential, the role's scopes may not exceed your own; a root API key (sk_) is exempt. Requires the profiles:u scope.

    • deleteRole

      public CompletableFuture<Void> deleteRole(String contextId, String roleId)
      Deletes a role. A role that is still referenced by one or more access profiles cannot be deleted: the request is rejected with 409. Reassign or delete those profiles first, then retry. Requires the profiles:d scope.

    • deleteRole

      public CompletableFuture<Void> deleteRole(String contextId, String roleId, RequestOptions requestOptions)
      Deletes a role. A role that is still referenced by one or more access profiles cannot be deleted: the request is rejected with 409. Reassign or delete those profiles first, then retry. Requires the profiles:d scope.

    • deleteRole

      public CompletableFuture<Void> deleteRole(String contextId, String roleId, DeleteRoleRequest request)
      Deletes a role. A role that is still referenced by one or more access profiles cannot be deleted: the request is rejected with 409. Reassign or delete those profiles first, then retry. Requires the profiles:d scope.

    • deleteRole

      public CompletableFuture<Void> deleteRole(String contextId, String roleId, DeleteRoleRequest request, RequestOptions requestOptions)
      Deletes a role. A role that is still referenced by one or more access profiles cannot be deleted: the request is rejected with 409. Reassign or delete those profiles first, then retry. Requires the profiles:d scope.

    • getAccessProfileVersions

      public CompletableFuture<ModelDataVersionPage> getAccessProfileVersions(String contextId, String principalId)
      Returns the audit trail of changes (create, update, and delete events) for an access profile, most recent first. Version history is always recorded for every access profile; there is no setting to turn it off. Results are paginated. Requires the profiles:r scope.

    • getAccessProfileVersions

      public CompletableFuture<ModelDataVersionPage> getAccessProfileVersions(String contextId, String principalId, RequestOptions requestOptions)
      Returns the audit trail of changes (create, update, and delete events) for an access profile, most recent first. Version history is always recorded for every access profile; there is no setting to turn it off. Results are paginated. Requires the profiles:r scope.

    • getAccessProfileVersions

      public CompletableFuture<ModelDataVersionPage> getAccessProfileVersions(String contextId, String principalId, GetAccessProfileVersionsRequest request)
      Returns the audit trail of changes (create, update, and delete events) for an access profile, most recent first. Version history is always recorded for every access profile; there is no setting to turn it off. Results are paginated. Requires the profiles:r scope.

    • getAccessProfileVersions

      public CompletableFuture<ModelDataVersionPage> getAccessProfileVersions(String contextId, String principalId, GetAccessProfileVersionsRequest request, RequestOptions requestOptions)
      Returns the audit trail of changes (create, update, and delete events) for an access profile, most recent first. Version history is always recorded for every access profile; there is no setting to turn it off. Results are paginated. Requires the profiles:r scope.

    • getRoleVersions

      public CompletableFuture<ModelDataVersionPage> getRoleVersions(String contextId, String roleId)
      Returns the audit trail of changes (create, update, and delete events) for a role, newest first. Version history is always recorded for every role; there is no setting to turn it off. Results are paginated. Requires the profiles:r scope.

    • getRoleVersions

      public CompletableFuture<ModelDataVersionPage> getRoleVersions(String contextId, String roleId, RequestOptions requestOptions)
      Returns the audit trail of changes (create, update, and delete events) for a role, newest first. Version history is always recorded for every role; there is no setting to turn it off. Results are paginated. Requires the profiles:r scope.

    • getRoleVersions

      public CompletableFuture<ModelDataVersionPage> getRoleVersions(String contextId, String roleId, GetRoleVersionsRequest request)
      Returns the audit trail of changes (create, update, and delete events) for a role, newest first. Version history is always recorded for every role; there is no setting to turn it off. Results are paginated. Requires the profiles:r scope.

    • getRoleVersions

      public CompletableFuture<ModelDataVersionPage> getRoleVersions(String contextId, String roleId, GetRoleVersionsRequest request, RequestOptions requestOptions)
      Returns the audit trail of changes (create, update, and delete events) for a role, newest first. Version history is always recorded for every role; there is no setting to turn it off. Results are paginated. Requires the profiles:r scope.

    • getUsage

      public CompletableFuture<UsageReportResponse> getUsage()
      Returns full usage detail for the requested calendar month, broken down by category (search, documents, and records) with per-category credit estimates and a split between your live and test environments. Defaults to the current month when year and month are omitted. Requires the billing:r scope on scoped tokens; API keys always have access. A token confined to a single app context sees only that context's usage: totals, the environment split, and the contexts breakdown narrow to it, and the environment your context is not bound to is omitted (null), not zeroed. Only a token with cross-context reach sees your full account-wide totals. Two exceptions to the narrowing, since they have no per-context breakdown to narrow to: reads.calls.used/reads.dataOut.bytes (metered per account, not per context) read as 0 for a confined token rather than a narrowed figure — the corresponding overage-credit charge fields narrow correctly; and credits.limit stays your whole plan's ceiling, so credits.remaining may overstate the account's true remaining room.

    • getUsage

      public CompletableFuture<UsageReportResponse> getUsage(RequestOptions requestOptions)
      Returns full usage detail for the requested calendar month, broken down by category (search, documents, and records) with per-category credit estimates and a split between your live and test environments. Defaults to the current month when year and month are omitted. Requires the billing:r scope on scoped tokens; API keys always have access. A token confined to a single app context sees only that context's usage: totals, the environment split, and the contexts breakdown narrow to it, and the environment your context is not bound to is omitted (null), not zeroed. Only a token with cross-context reach sees your full account-wide totals. Two exceptions to the narrowing, since they have no per-context breakdown to narrow to: reads.calls.used/reads.dataOut.bytes (metered per account, not per context) read as 0 for a confined token rather than a narrowed figure — the corresponding overage-credit charge fields narrow correctly; and credits.limit stays your whole plan's ceiling, so credits.remaining may overstate the account's true remaining room.

    • getUsage

      public CompletableFuture<UsageReportResponse> getUsage(GetUsageRequest request)
      Returns full usage detail for the requested calendar month, broken down by category (search, documents, and records) with per-category credit estimates and a split between your live and test environments. Defaults to the current month when year and month are omitted. Requires the billing:r scope on scoped tokens; API keys always have access. A token confined to a single app context sees only that context's usage: totals, the environment split, and the contexts breakdown narrow to it, and the environment your context is not bound to is omitted (null), not zeroed. Only a token with cross-context reach sees your full account-wide totals. Two exceptions to the narrowing, since they have no per-context breakdown to narrow to: reads.calls.used/reads.dataOut.bytes (metered per account, not per context) read as 0 for a confined token rather than a narrowed figure — the corresponding overage-credit charge fields narrow correctly; and credits.limit stays your whole plan's ceiling, so credits.remaining may overstate the account's true remaining room.

    • getUsage

      public CompletableFuture<UsageReportResponse> getUsage(GetUsageRequest request, RequestOptions requestOptions)
      Returns full usage detail for the requested calendar month, broken down by category (search, documents, and records) with per-category credit estimates and a split between your live and test environments. Defaults to the current month when year and month are omitted. Requires the billing:r scope on scoped tokens; API keys always have access. A token confined to a single app context sees only that context's usage: totals, the environment split, and the contexts breakdown narrow to it, and the environment your context is not bound to is omitted (null), not zeroed. Only a token with cross-context reach sees your full account-wide totals. Two exceptions to the narrowing, since they have no per-context breakdown to narrow to: reads.calls.used/reads.dataOut.bytes (metered per account, not per context) read as 0 for a confined token rather than a narrowed figure — the corresponding overage-credit charge fields narrow correctly; and credits.limit stays your whole plan's ceiling, so credits.remaining may overstate the account's true remaining room.

    • getIssuer

      public CompletableFuture<IssuerResponse> getIssuer(String issuerId)
      Retrieves a single registered issuer by issuerId. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key sees every context. An ordinary bootstrap credential that didn't specify a context resolves to the default app context specifically, not every context — so this call returns 404 for an issuer registered under any other context unless you re-minted the bootstrap token pinned to that context.

    • getIssuer

      public CompletableFuture<IssuerResponse> getIssuer(String issuerId, RequestOptions requestOptions)
      Retrieves a single registered issuer by issuerId. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key sees every context. An ordinary bootstrap credential that didn't specify a context resolves to the default app context specifically, not every context — so this call returns 404 for an issuer registered under any other context unless you re-minted the bootstrap token pinned to that context.

    • getIssuer

      public CompletableFuture<IssuerResponse> getIssuer(String issuerId, GetIssuerRequest request)
      Retrieves a single registered issuer by issuerId. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key sees every context. An ordinary bootstrap credential that didn't specify a context resolves to the default app context specifically, not every context — so this call returns 404 for an issuer registered under any other context unless you re-minted the bootstrap token pinned to that context.

    • getIssuer

      public CompletableFuture<IssuerResponse> getIssuer(String issuerId, GetIssuerRequest request, RequestOptions requestOptions)
      Retrieves a single registered issuer by issuerId. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key sees every context. An ordinary bootstrap credential that didn't specify a context resolves to the default app context specifically, not every context — so this call returns 404 for an issuer registered under any other context unless you re-minted the bootstrap token pinned to that context.

    • updateIssuer

      public CompletableFuture<IssuerResponse> updateIssuer(String issuerId)
      Updates the mutable fields of a registered issuer: subClaim, emailClaim, status (active/suspended — a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and selfSignupPolicies. Fields omitted from the body are left unchanged (partial update). issuer, jwksUri, audience, and contextId are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.

    • updateIssuer

      public CompletableFuture<IssuerResponse> updateIssuer(String issuerId, RequestOptions requestOptions)
      Updates the mutable fields of a registered issuer: subClaim, emailClaim, status (active/suspended — a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and selfSignupPolicies. Fields omitted from the body are left unchanged (partial update). issuer, jwksUri, audience, and contextId are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.

    • updateIssuer

      public CompletableFuture<IssuerResponse> updateIssuer(String issuerId, IssuerUpdateRequest request)
      Updates the mutable fields of a registered issuer: subClaim, emailClaim, status (active/suspended — a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and selfSignupPolicies. Fields omitted from the body are left unchanged (partial update). issuer, jwksUri, audience, and contextId are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.

    • updateIssuer

      public CompletableFuture<IssuerResponse> updateIssuer(String issuerId, IssuerUpdateRequest request, RequestOptions requestOptions)
      Updates the mutable fields of a registered issuer: subClaim, emailClaim, status (active/suspended — a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and selfSignupPolicies. Fields omitted from the body are left unchanged (partial update). issuer, jwksUri, audience, and contextId are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.

    • deleteIssuer

      public CompletableFuture<Void> deleteIssuer(String issuerId)
      Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through POST /v1/auth/token/exchange) — that access cannot be silently orphaned. Deactivate the affected users first if you intend to cut off their access, or register a replacement issuer before removing this one. An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.

    • deleteIssuer

      public CompletableFuture<Void> deleteIssuer(String issuerId, RequestOptions requestOptions)
      Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through POST /v1/auth/token/exchange) — that access cannot be silently orphaned. Deactivate the affected users first if you intend to cut off their access, or register a replacement issuer before removing this one. An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.

    • deleteIssuer

      public CompletableFuture<Void> deleteIssuer(String issuerId, DeleteIssuerRequest request)
      Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through POST /v1/auth/token/exchange) — that access cannot be silently orphaned. Deactivate the affected users first if you intend to cut off their access, or register a replacement issuer before removing this one. An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.

    • deleteIssuer

      public CompletableFuture<Void> deleteIssuer(String issuerId, DeleteIssuerRequest request, RequestOptions requestOptions)
      Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through POST /v1/auth/token/exchange) — that access cannot be silently orphaned. Deactivate the affected users first if you intend to cut off their access, or register a replacement issuer before removing this one. An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.

    • listIssuers

      public CompletableFuture<IssuerPage> listIssuers()
      Returns the issuers registered in your tenant. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only the issuers registered in that context; a root API key sees every context. An ordinary bootstrap credential that didn't specify a context resolves to the default app context specifically, not every context — so this call returns an empty page for a tenant whose issuers are all registered under a different context unless you re-minted the bootstrap token pinned to that context. Returns a {data, nextCursor} envelope.

    • listIssuers

      public CompletableFuture<IssuerPage> listIssuers(RequestOptions requestOptions)
      Returns the issuers registered in your tenant. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only the issuers registered in that context; a root API key sees every context. An ordinary bootstrap credential that didn't specify a context resolves to the default app context specifically, not every context — so this call returns an empty page for a tenant whose issuers are all registered under a different context unless you re-minted the bootstrap token pinned to that context. Returns a {data, nextCursor} envelope.

    • listIssuers

      public CompletableFuture<IssuerPage> listIssuers(ListIssuersRequest request)
      Returns the issuers registered in your tenant. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only the issuers registered in that context; a root API key sees every context. An ordinary bootstrap credential that didn't specify a context resolves to the default app context specifically, not every context — so this call returns an empty page for a tenant whose issuers are all registered under a different context unless you re-minted the bootstrap token pinned to that context. Returns a {data, nextCursor} envelope.

    • listIssuers

      public CompletableFuture<IssuerPage> listIssuers(ListIssuersRequest request, RequestOptions requestOptions)
      Returns the issuers registered in your tenant. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only the issuers registered in that context; a root API key sees every context. An ordinary bootstrap credential that didn't specify a context resolves to the default app context specifically, not every context — so this call returns an empty page for a tenant whose issuers are all registered under a different context unless you re-minted the bootstrap token pinned to that context. Returns a {data, nextCursor} envelope.

    • registerIssuer

      public CompletableFuture<IssuerResponse> registerIssuer(IssuerRequest request)
      Registers a trusted third-party IdP issuer that BYO-IdP token exchange (POST /v1/auth/token/exchange) may accept a subject_token from. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. A credential authorized only via the provisioning capability may register only against the app context it is bound to; naming a different one returns 403. A root API key is unaffected and may register against any of its contexts. Idempotent by issuerId within your tenant; the (issuer, audience) pair must not already be registered by a different issuerId/tenant. If issuerId collides with a registration owned by a different app context than the one you're confined to, the request fails with 400 rather than returning that context's configuration. An app context may have at most one active issuer — deregister the existing one first if you need to replace it. One issuer MAY serve several contexts today, each via its own registration row with a distinct audience.

    • registerIssuer

      public CompletableFuture<IssuerResponse> registerIssuer(IssuerRequest request, RequestOptions requestOptions)
      Registers a trusted third-party IdP issuer that BYO-IdP token exchange (POST /v1/auth/token/exchange) may accept a subject_token from. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. A credential authorized only via the provisioning capability may register only against the app context it is bound to; naming a different one returns 403. A root API key is unaffected and may register against any of its contexts. Idempotent by issuerId within your tenant; the (issuer, audience) pair must not already be registered by a different issuerId/tenant. If issuerId collides with a registration owned by a different app context than the one you're confined to, the request fails with 400 rather than returning that context's configuration. An app context may have at most one active issuer — deregister the existing one first if you need to replace it. One issuer MAY serve several contexts today, each via its own registration row with a distinct audience.

    • ping

      public CompletableFuture<PingResponse> ping()
      Returns the identity bound to your credential — your account, principal type, key id, and scope details — so you can confirm who you are authenticated as and that the credential is valid. MCP clients use this to render "signed in as ..." in a chat UI without a separate identity endpoint.

    • ping

      public CompletableFuture<PingResponse> ping(RequestOptions requestOptions)
      Returns the identity bound to your credential — your account, principal type, key id, and scope details — so you can confirm who you are authenticated as and that the credential is valid. MCP clients use this to render "signed in as ..." in a chat UI without a separate identity endpoint.

    • listProfilesForPrincipal

      public CompletableFuture<AccessProfilePage> listProfilesForPrincipal(String principalId)
      Returns the access profiles for the given principal. Looking up your OWN principal — or holding the context-directory-read capability — returns the profiles across ALL of your contexts, letting you answer questions like "which apps does this user have access to?". A context-bound credential looking up a DIFFERENT principal instead sees only that principal's profile in your credential's own context (at most one result), never across contexts it has no authority over. Results are always confined to your account. Requires the profiles:r scope.

    • listProfilesForPrincipal

      public CompletableFuture<AccessProfilePage> listProfilesForPrincipal(String principalId, RequestOptions requestOptions)
      Returns the access profiles for the given principal. Looking up your OWN principal — or holding the context-directory-read capability — returns the profiles across ALL of your contexts, letting you answer questions like "which apps does this user have access to?". A context-bound credential looking up a DIFFERENT principal instead sees only that principal's profile in your credential's own context (at most one result), never across contexts it has no authority over. Results are always confined to your account. Requires the profiles:r scope.

    • listProfilesForPrincipal

      public CompletableFuture<AccessProfilePage> listProfilesForPrincipal(String principalId, ListProfilesForPrincipalRequest request)
      Returns the access profiles for the given principal. Looking up your OWN principal — or holding the context-directory-read capability — returns the profiles across ALL of your contexts, letting you answer questions like "which apps does this user have access to?". A context-bound credential looking up a DIFFERENT principal instead sees only that principal's profile in your credential's own context (at most one result), never across contexts it has no authority over. Results are always confined to your account. Requires the profiles:r scope.

    • listProfilesForPrincipal

      public CompletableFuture<AccessProfilePage> listProfilesForPrincipal(String principalId, ListProfilesForPrincipalRequest request, RequestOptions requestOptions)
      Returns the access profiles for the given principal. Looking up your OWN principal — or holding the context-directory-read capability — returns the profiles across ALL of your contexts, letting you answer questions like "which apps does this user have access to?". A context-bound credential looking up a DIFFERENT principal instead sees only that principal's profile in your credential's own context (at most one result), never across contexts it has no authority over. Results are always confined to your account. Requires the profiles:r scope.

    • mintToken

      public CompletableFuture<MintTokenResponse> mintToken(TokenRequest request)
      Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user or identity entity (in any namespace). Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (sk_*).

    • mintToken

      public CompletableFuture<MintTokenResponse> mintToken(TokenRequest request, RequestOptions requestOptions)
      Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user or identity entity (in any namespace). Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (sk_*).

    • createInvite

      public CompletableFuture<CreateInviteResponse> createInvite(CreateInviteRequest request)
      Invite a new member to one of your app contexts by email, OR grant an existing member access to an additional app context by inviting their same email again. Idempotent on the combination of context and email: re-inviting the same email into the SAME context rotates the token and resends the invitation rather than creating a duplicate — this requires the users:r and users:u scopes in addition to users:c, because resending rotates a credential on an existing invitation and invalidates any link already sent. Without them the collision returns 409 instead, with no invitation details and no change to the outstanding invitation. Inviting the SAME email into a DIFFERENT app context in this tenant, where that email already resolves to an existing member: if that member is active AND already has (or, once accepted, will have) a credential that works for the new context's own identity provider, this immediately grants them access to the new context (no email is sent — there is nothing to accept, emailSent is false) — this additionally requires the users:r scope (no users:u, since nothing is mutated), because the response names the existing member's userId, a fact about them your credential could not otherwise learn through this endpoint. If that active member's ONLY existing credential is for a DIFFERENT identity provider than the one the new context uses, a normal, independent invitation is created instead (its own new member id, a real token/accept link) — attaching them silently would leave no way for them to ever actually sign in to that context. If the existing member's original invitation is still pending, this attaches the new context's access to that same outstanding invitation and rotates its token (users:r+users:u, same as an ordinary resend — both the disclosure and the credential rotation apply here). A SUSPENDED member's email does not get new-context access this way — reactivate them explicitly first. Returns HTTP 201 in every one of those cases. Returns 409 if that email already belongs to an active or suspended member of THIS specific app context, already has a PENDING invitation for THIS specific app context, or resolves to an existing member elsewhere in the tenant and your token lacks the additional scope the grant/attach requires (users:r, or users:r+users:u for the still-pending case). An email that already has an identity in your OTHER tenant (test vs. live) is not a collision either — it creates an additional, independent membership in this tenant for that same identity. When sendEmail is false, the response includes the raw token and a ready-to-use accept link so you can deliver the invitation through your own email provider. Requires the users:c scope — or, for a credential scoped to a single app context, the member-lifecycle capability plus the matching profiles:c/profiles:r/profiles:u grant(s) in that context, as an equally sufficient alternative to every users:c/users:r/users:u requirement in this description.

    • createInvite

      public CompletableFuture<CreateInviteResponse> createInvite(CreateInviteRequest request, RequestOptions requestOptions)
      Invite a new member to one of your app contexts by email, OR grant an existing member access to an additional app context by inviting their same email again. Idempotent on the combination of context and email: re-inviting the same email into the SAME context rotates the token and resends the invitation rather than creating a duplicate — this requires the users:r and users:u scopes in addition to users:c, because resending rotates a credential on an existing invitation and invalidates any link already sent. Without them the collision returns 409 instead, with no invitation details and no change to the outstanding invitation. Inviting the SAME email into a DIFFERENT app context in this tenant, where that email already resolves to an existing member: if that member is active AND already has (or, once accepted, will have) a credential that works for the new context's own identity provider, this immediately grants them access to the new context (no email is sent — there is nothing to accept, emailSent is false) — this additionally requires the users:r scope (no users:u, since nothing is mutated), because the response names the existing member's userId, a fact about them your credential could not otherwise learn through this endpoint. If that active member's ONLY existing credential is for a DIFFERENT identity provider than the one the new context uses, a normal, independent invitation is created instead (its own new member id, a real token/accept link) — attaching them silently would leave no way for them to ever actually sign in to that context. If the existing member's original invitation is still pending, this attaches the new context's access to that same outstanding invitation and rotates its token (users:r+users:u, same as an ordinary resend — both the disclosure and the credential rotation apply here). A SUSPENDED member's email does not get new-context access this way — reactivate them explicitly first. Returns HTTP 201 in every one of those cases. Returns 409 if that email already belongs to an active or suspended member of THIS specific app context, already has a PENDING invitation for THIS specific app context, or resolves to an existing member elsewhere in the tenant and your token lacks the additional scope the grant/attach requires (users:r, or users:r+users:u for the still-pending case). An email that already has an identity in your OTHER tenant (test vs. live) is not a collision either — it creates an additional, independent membership in this tenant for that same identity. When sendEmail is false, the response includes the raw token and a ready-to-use accept link so you can deliver the invitation through your own email provider. Requires the users:c scope — or, for a credential scoped to a single app context, the member-lifecycle capability plus the matching profiles:c/profiles:r/profiles:u grant(s) in that context, as an equally sufficient alternative to every users:c/users:r/users:u requirement in this description.

    • resendInvite

      public CompletableFuture<CreateInviteResponse> resendInvite(CreateInviteRequest request)
      Resend an outstanding invitation, identified by its email and app context. Rotates the invitation token and extends its expiry, then (when sendEmail is true) re-delivers the email. Rotating the token invalidates any previously issued link for this invitation, so only the newest link works. The invitee's pending permissions are left unchanged. Because this rotates a credential on an existing invitation, it requires the users:c, users:r and users:u scopes — or, for a credential scoped to a single app context, the member-lifecycle capability plus the matching profiles:c/profiles:r/profiles:u grant(s) in that context.

    • resendInvite

      public CompletableFuture<CreateInviteResponse> resendInvite(CreateInviteRequest request, RequestOptions requestOptions)
      Resend an outstanding invitation, identified by its email and app context. Rotates the invitation token and extends its expiry, then (when sendEmail is true) re-delivers the email. Rotating the token invalidates any previously issued link for this invitation, so only the newest link works. The invitee's pending permissions are left unchanged. Because this rotates a credential on an existing invitation, it requires the users:c, users:r and users:u scopes — or, for a credential scoped to a single app context, the member-lifecycle capability plus the matching profiles:c/profiles:r/profiles:u grant(s) in that context.

    • assumeToken

      public CompletableFuture<TokenAssumeResponse> assumeToken(Map<String,Object> request)
      Re-mints the presented st_* scoped token with one or more identity.<namespace> values changed — for a caller whose ROLE explicitly grants assuming those values (an invited hr-admin, a multi-org case-handler) and needs to change which value new writes place records under. The request body names one or more namespaces in canonical scope:<namespace> form, e.g. {"scope:org": "orgB"} — each value must be a plain literal, never a ${{ ... }} placeholder. When you name MORE THAN ONE namespace, a single one of your roles must grant all of them together: the combination is never assembled from two different roles, because no role author would have vouched for it. st_*-only — a root API key or ssk_* scoped API key gets 403; neither needs this (root already has full authority, and an ssk_*'s identity shape is not what this resolves against).

      Only an original token may assume. A token produced BY this endpoint cannot assume again (403) — every assume starts from the token you exchanged for, so the identity you end up with is always one a single role explicitly granted rather than a combination reached by chaining calls. Keep your original token if you need to switch more than once, or exchange for a new one.

      Entitlement is checked LIVE, against your roles as they are right now — not against a copy frozen into your token when it was minted. The requested value must be explicitly granted by a role's assumable field for that namespace: a POINT check against the one value requested, and a deliberately separate, explicitly-authored question from what the role's data_scope permits reading or writing. Holding broad data_scope reach in a namespace does NOT by itself grant assuming any value in it.

      What is preserved, and what is not. Every clause of your token that does not reference a requested namespace is preserved verbatim, as are all other claims (partner_user_id, context_id, mint attribution). Clauses that DO reference a requested namespace are kept only if they come from a role that authorized the new value. A role that does not authorize it loses all of its clauses touching that namespace — including any scoped to the value you already held. Assume into a value one role grants and you keep that role's reach, not the reach of roles that never vouched for it.

      The re-minted token's exp is IDENTICAL to the presented token's — this call can never extend a session's life. A fresh, independently-revocable jti is stamped on every call, and (except when the presented token predates jti support and has none to chain from) the token also carries a root_jti revocation-lineage claim so revoking the token you started from closes every value ever assumed from it. Uses the ordinary Vectros {"message":...} error shape, not the OAuth envelope POST /v1/auth/token/exchange uses — this endpoint's caller is always Vectros-SDK code already holding a bearer token, never generic OAuth tooling.

    • assumeToken

      public CompletableFuture<TokenAssumeResponse> assumeToken(Map<String,Object> request, RequestOptions requestOptions)
      Re-mints the presented st_* scoped token with one or more identity.<namespace> values changed — for a caller whose ROLE explicitly grants assuming those values (an invited hr-admin, a multi-org case-handler) and needs to change which value new writes place records under. The request body names one or more namespaces in canonical scope:<namespace> form, e.g. {"scope:org": "orgB"} — each value must be a plain literal, never a ${{ ... }} placeholder. When you name MORE THAN ONE namespace, a single one of your roles must grant all of them together: the combination is never assembled from two different roles, because no role author would have vouched for it. st_*-only — a root API key or ssk_* scoped API key gets 403; neither needs this (root already has full authority, and an ssk_*'s identity shape is not what this resolves against).

      Only an original token may assume. A token produced BY this endpoint cannot assume again (403) — every assume starts from the token you exchanged for, so the identity you end up with is always one a single role explicitly granted rather than a combination reached by chaining calls. Keep your original token if you need to switch more than once, or exchange for a new one.

      Entitlement is checked LIVE, against your roles as they are right now — not against a copy frozen into your token when it was minted. The requested value must be explicitly granted by a role's assumable field for that namespace: a POINT check against the one value requested, and a deliberately separate, explicitly-authored question from what the role's data_scope permits reading or writing. Holding broad data_scope reach in a namespace does NOT by itself grant assuming any value in it.

      What is preserved, and what is not. Every clause of your token that does not reference a requested namespace is preserved verbatim, as are all other claims (partner_user_id, context_id, mint attribution). Clauses that DO reference a requested namespace are kept only if they come from a role that authorized the new value. A role that does not authorize it loses all of its clauses touching that namespace — including any scoped to the value you already held. Assume into a value one role grants and you keep that role's reach, not the reach of roles that never vouched for it.

      The re-minted token's exp is IDENTICAL to the presented token's — this call can never extend a session's life. A fresh, independently-revocable jti is stamped on every call, and (except when the presented token predates jti support and has none to chain from) the token also carries a root_jti revocation-lineage claim so revoking the token you started from closes every value ever assumed from it. Uses the ordinary Vectros {"message":...} error shape, not the OAuth envelope POST /v1/auth/token/exchange uses — this endpoint's caller is always Vectros-SDK code already holding a bearer token, never generic OAuth tooling.

    • exchangeToken

      public CompletableFuture<TokenExchangeResponse> exchangeToken(TokenExchangeRequest request)
      RFC 8693 OAuth 2.0 Token Exchange. Trades a JWT issued by a third-party identity provider you've registered (POST /v1/auth/issuers) for a Vectros st_* scoped bearer token — no Vectros credential required to call this endpoint. The exchanged token's scope is resolved entirely server-side from the matched user's access profile; this endpoint accepts no caller-supplied scope, resource, or audience parameter (RFC 8693 §2.1's resource/audience/scope are not used in v1 — the registered (issuer, audience) pair alone pins the target tenant and app context). On a first-time login (no existing Vectros identity for this subject), two opt-in binding paths exist: invite_token (a PENDING sub-user invitation), and — if the registration declares one or more self-signup policies — signup_type (a brand-new user is created and bound to the policy's configured role). If invite_token is present at all, it is the ONLY path tried — a failed invite never falls through to self-signup. Neither field is required for a subject with an existing identity. If your issuer is registered against more than one app context (each via its own audience), context_id selects which one to target; omit it when your token's aud claim matches only one registered context — the common case, unaffected by this field. Uses the OAuth-standard error envelope ({"error":..., "error_description":...}, RFC 6749 §5.2), NOT this API's usual {"message":...} shape — its client is generic OAuth tooling, not the Vectros SDK.

    • exchangeToken

      public CompletableFuture<TokenExchangeResponse> exchangeToken(TokenExchangeRequest request, RequestOptions requestOptions)
      RFC 8693 OAuth 2.0 Token Exchange. Trades a JWT issued by a third-party identity provider you've registered (POST /v1/auth/issuers) for a Vectros st_* scoped bearer token — no Vectros credential required to call this endpoint. The exchanged token's scope is resolved entirely server-side from the matched user's access profile; this endpoint accepts no caller-supplied scope, resource, or audience parameter (RFC 8693 §2.1's resource/audience/scope are not used in v1 — the registered (issuer, audience) pair alone pins the target tenant and app context). On a first-time login (no existing Vectros identity for this subject), two opt-in binding paths exist: invite_token (a PENDING sub-user invitation), and — if the registration declares one or more self-signup policies — signup_type (a brand-new user is created and bound to the policy's configured role). If invite_token is present at all, it is the ONLY path tried — a failed invite never falls through to self-signup. Neither field is required for a subject with an existing identity. If your issuer is registered against more than one app context (each via its own audience), context_id selects which one to target; omit it when your token's aud claim matches only one registered context — the common case, unaffected by this field. Uses the OAuth-standard error envelope ({"error":..., "error_description":...}, RFC 6749 §5.2), NOT this API's usual {"message":...} shape — its client is generic OAuth tooling, not the Vectros SDK.