Package ai.vectros.resources.auth

Class AuthClient

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

  • Field Details

  • Constructor Details

  • Method Details

    • withRawResponse

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

    • getJwks

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

    • getAppContext

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

    • getAppContext

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

    • getAppContext

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

    • updateAppContext

      public AppContextResponse updateAppContext(String contextId, UpdateAppContextRequest request)
      Updates the name and/or description 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 AppContextResponse updateAppContext(String contextId, UpdateAppContextRequest request, RequestOptions requestOptions)
      Updates the name and/or description 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.

    • getIssuer

      public 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.

    • getIssuer

      public 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.

    • getIssuer

      public 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.

    • deleteIssuer

      public 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 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 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 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 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. Returns a {data, nextCursor} envelope.

    • listIssuers

      public 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. Returns a {data, nextCursor} envelope.

    • listIssuers

      public 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. Returns a {data, nextCursor} envelope.

    • listIssuers

      public 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. Returns a {data, nextCursor} envelope.

    • registerIssuer

      public 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 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 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 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 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 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 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 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 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 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 CreateInviteResponse createInvite(CreateInviteRequest request)
      Invite a new member to one of your app contexts by email. Creates a pending user with a pre-resolved access profile (their permissions on accept) and signs an invitation token. This call is idempotent on the combination of context and email: re-inviting the same email in 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. Returns HTTP 201 on a new invite or a successful resend. Returns 409 if that email already belongs to an active or suspended member of the app context, or already has an identity elsewhere in your account (an email can currently belong to only one tenant per account, i.e. your test and live environments cannot share an email). 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.

    • createInvite

      public CreateInviteResponse createInvite(CreateInviteRequest request, RequestOptions requestOptions)
      Invite a new member to one of your app contexts by email. Creates a pending user with a pre-resolved access profile (their permissions on accept) and signs an invitation token. This call is idempotent on the combination of context and email: re-inviting the same email in 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. Returns HTTP 201 on a new invite or a successful resend. Returns 409 if that email already belongs to an active or suspended member of the app context, or already has an identity elsewhere in your account (an email can currently belong to only one tenant per account, i.e. your test and live environments cannot share an email). 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.

    • resendInvite

      public 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.

    • resendInvite

      public 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.

    • exchangeToken

      public 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 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.