SlashID Persons API

openapi: 3.0.1
info:
  title: SlashID Groups Persons API
  description: "This is the [OpenAPI](https://www.openapis.org/) specification for communicating with the [SlashID](https://www.slashid.dev/) service.\n\nThe latest version of the OpenAPI API spec can be fetched from [our CDN](https://cdn.slashid.com/slashid-openapi-latest.yaml).\n\nWe recommend you use an [OpenAPI SDK generator](https://openapi.tools/#sdk) to create a client library in your programming language,\nbut you can also use this documentation to make HTTP calls directly.\n\n> **Compatibility note**: We aim to keep wire compatibility whenever we update the API, but parts of the specification may occasionally be refactored.\n  If you use an SDK generator, your code may require minor changes between versions.\n"
  version: '1.1'
  termsOfService: https://www.slashid.dev/terms-of-use/
  contact:
    name: API Support
    email: contact@slashid.dev
servers:
- url: https://api.slashid.com
  description: Production
- url: https://api.sandbox.slashid.com
  description: Sandbox
security:
- ApiKeyAuth: []
tags:
- name: Persons
paths:
  /persons/{person_id}/direct-id:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    post:
      operationId: PostPersonsPersonIdDirectId
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Get Direct-ID value for a person
      description: 'This endpoint creates a one-time Direct-ID for a specific user. The returned Direct-ID string can embedded in a URL in the `challenges` query parameter to let your users land on a target page already authenticated.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonDirectIDReq'
        required: true
      responses:
        '201':
          description: The result string is a Direct-ID you can include in your links in the `challenges` query parameter.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/DirectID'
                  required:
                  - result
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/mint-token:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    post:
      operationId: PostPersonsPersonIdMintToken
      tags:
      - Persons
      summary: Mint a token for a person
      description: "This endpoint creates a token for a specific user.\n\n\nCustom claims can be specified in the request body which will be added to the token's payload.\nCustom claims are added to the token's payload.\n\nTokens created with this endpoint will have an `authenticated_methods` claim equal to [\"api\"].\n\n\nThe following claims are reserved and cannot be specified:\n  - aud\n  - exp\n  - jti\n  - iat\n  - iss\n  - nbf\n  - sub\n  - prev_token_id\n  - oid\n  - org_id\n  - user_id\n  - person_id\n  - first_token\n  - authenticated_methods\n  - oidc_tokens\n  - user_token\n  - groups\n  - roles\n  - access_token\n  - refresh_token\n  - id\n  - id_token\n  - gdpr\n  - gdpr_consent\n  - gdpr_consent_level\n  - parent_user_id\n  - parent_person_id\n  - parent_org_id\n  - parent_oid\n  - attributes\n  - custom_claims\n  - slashid\n  - slashid.dev\n  - slashid.com\n  - slashid.me\n  - sid\n\n\nWith the following request body:\n\n\n```\n{\n    \"custom_claims\": {\n        \"foo\": \"bar\",\n        \"baz\": {\"everything\": 42}\n    }\n}\n```\n\n\nthe token in the response will have the following payload:\n\n```\n{\n  \"authenticated_methods\": [\n    \"api\"\n  ],\n  \"baz\": {\n    \"everything\": 42\n  },\n  \"exp\": <expiration time timestamp>,\n  \"first_token\": false,\n  \"foo\": \"bar\",\n  \"iat\": <issued at timestamp>,\n  \"iss\": <token issuer>,\n  \"jti\": <token ID>,\n  \"oid\": <organisation ID>,\n  \"person_id\": <person ID>\n}\n```\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMintTokenRequest'
        required: true
      responses:
        '201':
          description: The result string is a newly-minted SlashID token.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/UserTokenText'
                  required:
                  - result
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    get:
      operationId: GetPersonsPersonId
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member,impersonator
      x-manager-rbac-allowed-groups: admin,member,impersonator
      tags:
      - Persons
      summary: Retrieve a person
      description: 'Get a person object by its ID. The function returns the decrypted, abridged person record.


        Please use the Attributes API to retrieve custom person attributes.'
      parameters:
      - $ref: '#/components/parameters/PersonFieldsQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonRet'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: DeletePersonsPersonId
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      x-manager-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Delete a person from an organization
      description: 'Remove the person, specified by its ID, from the organization.


        Note that access to all the attributes associated with this person will be permanently revoked.'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: PatchPersonsPersonId
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Modify an existing person
      description: 'Modify configuration for an existing specific person associated with your organization. This includes the list of roles for the person and whether the person is active or not.

        '
      requestBody:
        description: The person patch request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonPatchReq'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonRet'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/groups:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    get:
      operationId: GetPersonsPersonIdGroups
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member,impersonator,saml-admin,uar-certifier,uar-campaign-manager,cs-id-verifier
      x-manager-rbac-allowed-groups: admin,member,impersonator,saml-admin,uar-certifier,uar-campaign-manager,cs-id-verifier
      tags:
      - Persons
      summary: Get groups for a person
      description: Retrieve the list of groups the specified person belongs to
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonGroupsResponse'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: PutPersonsPersonIdGroups
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      x-manager-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Set the groups for a person
      description: 'Add the person to the groups specified in the request body, and remove the person from any other existing groups.

        All groups in the request body must already exist. Duplicate groups in the request body will be ignored. If an empty list is supplied in the request body, the person will be removed from all groups they are currently a member of, and will not be added to any others.

        New groups can be created with the [POST /groups](/docs/api/post-groups) endpoint.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutPersonGroupsReq'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonGroupsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/permissions:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    get:
      operationId: GetPersonsPersonIdPermissions
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member
      tags:
      - Persons
      summary: Get permissions for a person
      description: Retrieve the list of permissions granted to the specified person. It contains both assigned permissions and permissions from roles.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonPermissionsResponse'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/additional-permissions:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    get:
      operationId: GetPersonsPersonIdAdditionalPermissions
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member
      tags:
      - Persons
      summary: Get additional permissions for a person
      description: Retrieve the list of additional permissions assigned to person. This endpoint doesn't return permissions from roles.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonPermissionsResponse'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: PutPersonsPersonIdPermissions
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Set the permissions for a person
      description: 'Grant the person the permissions specified in the request body, and revoke the person any other existing permissions.

        All permissions in the request body must already exist. Duplicate permissions in the request body will be ignored. If an empty list is supplied in the request body, the person will be revoked all permissions they currently have.

        '
      parameters:
      - $ref: '#/components/parameters/IfMatchHeader'
      - $ref: '#/components/parameters/RequiredConsistencyHeader'
      - $ref: '#/components/parameters/RequiredConsistencyTimeoutHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutPersonPermissionsRequest'
        required: true
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /persons/{person_id}/roles:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    get:
      operationId: GetPersonsPersonIdRoles
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member
      x-manager-rbac-allowed-groups: admin,member
      tags:
      - Persons
      summary: Get roles for a person
      description: Retrieve the list of roles granted to the specified person
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonRolesResponse'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: PutPersonsPersonIdRoles
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      x-manager-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Set the roles for a person
      description: 'Grant the person the roles specified in the request body, and revoke the person any other existing roles.

        All roles in the request body must already exist. Duplicate roles in the request body will be ignored. If an empty list is supplied in the request body, the person will be revoked all roles they currently have.

        '
      parameters:
      - $ref: '#/components/parameters/IfMatchHeader'
      - $ref: '#/components/parameters/RequiredConsistencyHeader'
      - $ref: '#/components/parameters/RequiredConsistencyTimeoutHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutPersonRolesRequest'
        required: true
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /persons/{person_id}/organizations:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    get:
      operationId: GetPersonsPersonIdOrganizations
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member
      tags:
      - Persons
      summary: Retrieve the list of person's organizations
      description: "Retrieve details of all the organizations a person belongs to, including:\n - The organization of the request: the person must be a member of the organization you authenticate\n   with for you to be allowed to retrieve this list\n - Any sub- and super-organizations that share the person pool with the organization of the request:\n   A hierarchy of organizations can be created using [this API endpoint](/docs/api/post-organizations-suborganizations).\n   When organizations are configured to share a person pool, if the same person registers with multiple organizations\n   in the pool using the same handle, all organizations will see the same person ID for that person.\n"
      parameters:
      - $ref: '#/components/parameters/GetPersonsPersonIdOrganizationsFilterQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/GetPersonOrganizationsResponse'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons:
    parameters:
    - $ref: '#/components/parameters/OrgIDHeader'
    post:
      operationId: PostPersons
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      x-manager-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Create new person
      description: 'Create a new person linked to your organization.

        The request must contain at least one handle for the person (email address, phone number, or username). Optionally, you can specify a list of roles, a geographical region and attributes. Attributes are a map from attribute bucket names to key-value pairs.

        If a person with the specified handles already exists, an error will be returned.

        If the region is not specified, the person will be created in the region closest to the region of your backend.

        If you explicitly specify the region and a person with the provided handle already exists in a different region, this endpoint will return an error.

        A person''s region association is eventually consistent between regions. Because of that, creating a person between regions within the time frame of data replication can result in a person being created in multiple regions. You can learn more on the [Cross-region replication model](/docs/access/concepts/replication) page.

        '
      requestBody:
        description: The person creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonCreateReq'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonsPostResponse'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    put:
      operationId: PutPersons
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Create or update a person (idempotent)
      description: 'This endpoint works as the [`POST /persons`](/docs/api/post-persons) endpoint, except that it is idempotent. If the person already exists, it will be updated with the new data and 200 status code will be returned.

        '
      requestBody:
        description: The person creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonCreateReq'
        required: true
      responses:
        '200':
          description: OK - person already exists and was updated
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonsPutResponse'
                  required:
                  - result
        '201':
          description: Created - person was created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonsPutResponse'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      operationId: GetPersons
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member,impersonator
      x-manager-rbac-allowed-groups: admin,member,impersonator
      tags:
      - Persons
      summary: Retrieve a list of persons
      description: Retrieve the full list of persons in your organization.
      parameters:
      - $ref: '#/components/parameters/HandleQueryParam'
      - $ref: '#/components/parameters/PersonsFilterQueryParam'
      - $ref: '#/components/parameters/LimitQueryParam'
      - $ref: '#/components/parameters/OffsetQueryParam'
      - $ref: '#/components/parameters/PersonIDsQueryParam'
      - $ref: '#/components/parameters/PersonFieldsQueryParam'
      - in: query
        name: all_regions
        schema:
          type: boolean
          default: true
        description: If true, users from all regions will be returned. Defaults to true.
      - in: query
        name: all_person_types
        schema:
          type: boolean
          default: false
        description: If true, also returns non-regular users. Defaults to false.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      type: array
                      items:
                        $ref: '#/components/schemas/PersonRet'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /groups/{group_name}/persons:
    parameters:
    - $ref: '#/components/parameters/OrgIDHeader'
    - $ref: '#/components/parameters/GroupNamePathParam'
    post:
      operationId: PostGroupsGroupNamePersons
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Add persons to a group
      description: 'This endpoint adds one or more persons to an existing group. The group and all of the persons must exist. The persons to be added to the group must always be an array in the request body, even if only one user is being added. All persons needs to be in the same region.

        A new group can be created with the [POST /groups](/docs/api/post-groups) endpoint.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostGroupPersonsReq'
        required: true
      responses:
        '201':
          description: The persons were successfully added to the group
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      operationId: GetGroupsGroupNamePersons
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member
      tags:
      - Persons
      summary: List the persons in a group
      description: Lists all the persons in the named group. Returns an array of person IDs.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      type: array
                      items:
                        type: string
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /groups/{group_name}/persons/{person_id}:
    parameters:
    - $ref: '#/components/parameters/OrgIDHeader'
    - $ref: '#/components/parameters/GroupNamePathParam'
    - $ref: '#/components/parameters/PersonIDPathParam'
    delete:
      operationId: DeleteGroupsGroupNamePersonsPersonId
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Persons
      summary: Delete a person from a group
      description: 'Removes the identified person from the named group. Returns an error if the person is not in the group.

        '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponseBase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponseBase'
    NoContent:
      description: No content
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponseBase'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponseBase'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponseBase'
    PaymentRequired:
      description: Pricing Tier Violation - operation violated the limits specified in its pricing tier.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponseBase'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponseBase'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponseBase'
  schemas:
    PublicKeyAuthenticator:
      type: object
      required:
      - aaguid
      properties:
        aaguid:
          type: string
          description: Base64-encoded AAGUID of the authenticator device
        sign_count:
          type: integer
        clone_warning:
          type: boolean
    Bytes:
      type: string
    PasswordCredentialParams:
      type: object
      required:
      - password_hash
      properties:
        password_hash:
          type: string
          description: "A hash of a password, in the one of the formats accepts by SlashID.\nSlashID supports the following hashing functions:\n  - pbkdf2\n  - bcrypt\n  - argon2i\n  - argon2id\nHashes created using a function not listed here will be rejected.\nIn all of these cases, SlashID accepts hashes in the format described [here](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md).\nThe only departure from the specification described is that the hashing function version can include the characters [a-z0-9], to accommodate bcrypt versions (2, 2a, 2b, 2x, 2y).\nSlashID also accepts password hashes in the format used by [bcrypt](https://www.usenix.org/legacy/events/usenix99/provos/provos.pdf).\nIf a password hash matches this format, it is assumed that the hashing function used was bcrypt.\nIf any other hashing function was used to hash the password, the hash must be in the SlashID hash format.\n"
    Organization:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/OrganizationID'
        parent_id:
          $ref: '#/components/schemas/OrganizationID'
        org_name:
          type: string
        tenant_name:
          type: string
      required:
      - id
      - org_name
      - tenant_name
    PersonsPostResponse:
      $ref: '#/components/schemas/PersonRet'
    TOTPCredentialParams:
      type: object
      required:
      - key_uri
      - recovery_codes_total
      - unused_recovery_codes
      properties:
        key_uri:
          type: string
          description: "The TOTP key URI of the authenticator you wish to import, in Google Authenticator / Yubico format:\n```\notpauth://totp/[Issuer]:[Account name]?secret=[Secret key]&issuer=[Issuer]&algorithm=[Algorithm]&digits=[Digits number]&period=[Period in seconds]\n```\nwhere:\n  - `Issuer`: a string value indicating the provider or service this account is associated with, URL-encoded according to RFC 3986. When users register TOTP authenticators with SlashID this value is the Organization name. It is **strongly recommended** that the same value is used in both the `Account name` prefix and in the `issuer` parameter to maximize compatibility across different authenticator apps/devices.\n  - `Account name`: a string value usually diplayed by authenticators to end users to help them distinguish between their TOTP keys. When users register TOTP authenticators with SlashID this value is the handle (e-mail address or phone number) the user authenticated with when they registered the TOTP credential.\n  - `Secret key`: an arbitrary key value encoded in Base32 according to RFC 3548. The padding specified in RFC 3548 section 2.2 is not required and should be omitted.\n  - `Algorithm` (optional): the hashing algorithm to use. Valid values are `SHA1`, `SHA256`, `SHA512`. Defaults to `SHA1`.\n  - `Digits number` (optional): determines the length of the one-time passcode displayed to the user. Valid values are `6`, `8`. Defaults to `6`.\n  - `Period in seconds` (optional): defines the period that a TOTP code will be valid for, in seconds. Defaults to `30`.\n\nAn example with all optional parameters supplied:\n```\notpauth://totp/ACME%20Co:john.doe@email.com?secret=HXDMVJECJJWSRB3HWIZR4IFUGFTMXBOZ&issuer=ACME%20Co&algorithm=SHA1&digits=6&period=30\n```\n"
          example: otpauth://totp/ACME%20Co:john.doe@email.com?secret=HXDMVJECJJWSRB3HWIZR4IFUGFTMXBOZ&issuer=ACME%20Co&algorithm=SHA1&digits=6&period=30
        recovery_codes_total:
          type: integer
          minimum: 0
          description: The total number of recovery codes originally issued to the given person.
        unused_recovery_codes:
          type: array
          items:
            type: string
          description: The list of recovery codes the given person can still use in the future in place of TOTP codes. Once imported these codes will be treated as single-use.
    PersonHandle:
      required:
      - type
      - value
  

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/slashid/refs/heads/main/openapi/slashid-persons-api-openapi.yml