openapi: 3.0.1
info:
  title: SlashID Groups Person Credentials 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: Person Credentials
paths:
  /persons/{person_id}/credentials:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    get:
      operationId: GetPersonsPersonIdCredentials
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member
      tags:
      - Person Credentials
      summary: Retrieve a person's credentials
      description: 'Retrieves credentials linked to the specified person in your organization.

        '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      type: array
                      items:
                        $ref: '#/components/schemas/ExportedCredential'
                  required:
                  - result
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: PostPersonsPersonIdCredentials
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Person Credentials
      summary: Create a new credential
      description: 'Creates a new credential linked to the specified person in your organization. This credential will then be available for use in future authentication challenges.

        '
      requestBody:
        description: The credential creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Credential'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/ExportedCredential'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: DeletePersonsPersonIdCredentials
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Person Credentials
      summary: Delete all credentials
      description: 'Deletes all credentials from a person. Note that deletion is irreversible and the credentials will no longer be usable for authentication.

        '
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/credentials/{credential_id}:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/CredentialIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    delete:
      operationId: DeletePersonsPersonIdCredentialsCredentialId
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Person Credentials
      summary: Delete a credential object
      description: 'Deletes the specified credential from a person,organization pair. Note that deletion is irreversible and the credential will no longer be usable for authentication.

        '
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/credentials/password:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    put:
      operationId: PutPersonsPersonIdCredentialsPassword
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Person Credentials
      summary: Create or overwrite a password credential.
      description: 'Creates or overwrites the password credential linked to the specified person in your organization. This credential will then be available for use in future authentication challenges.

        '
      requestBody:
        description: The password credential creation/overwrite request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordCredential'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/credentials/password-reset:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    post:
      operationId: PostPersonsPersonIdCredentialsPasswordReset
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Person Credentials
      summary: Trigger a password reset flow
      description: 'Triggers a password reset flow for the specified person and credential. The specified person must then take action to complete the flow and set a new password. Optionally, you can specify which of the person''s handles will be used to send the password reset link.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetPostReq'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/credentials/password-rotate:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    post:
      operationId: PostPersonsPersonIdCredentialsPasswordRotate
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Person Credentials
      summary: Rotate a person's password
      description: 'Rotates a person''s password. The specified person does not need to have an existing password credential. A new password credential will be created regardless and returned in the response.

        '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PasswordRotatePostResp'
                  required:
                  - result
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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
    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"
    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.
    PasswordResetPostReq:
      type: object
      properties:
        force_change:
          type: boolean
          description: Delete the existing password for a person, forcing a new password to be set before the next password authentication.
        reset_handle:
          $ref: '#/components/schemas/PersonHandle'
    PersonHandle:
      required:
      - type
      - value
      type: object
      properties:
        type:
          $ref: '#/components/schemas/PersonHandleType'
        value:
          type: string
          example: user@user.com
    PublicKeyCredentialParams:
      type: object
      required:
      - webauthn_credential_id
      - public_key
      - attestation_type
      - authenticator
      properties:
        webauthn_credential_id:
          type: string
          description: The ID of the webauthn credential
        public_key:
          type: string
          description: Base64-encoded public key
        attestation_type:
          type: string
          description: The attestation type for the public key (defaults to "none")
        authenticator:
          $ref: '#/components/schemas/PublicKeyAuthenticator'
    PasswordCredential:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CredentialType'
        params:
          $ref: '#/components/schemas/PasswordCredentialParams'
        label:
          type: string
      required:
      - type
      - params
    APIResponseBase:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/APIMeta'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/APIResponseError'
    APIPagination:
      type: object
      required:
      - limit
      - offset
      - total_count
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total_count:
          type: integer
          format: int64
    ExportedCredential:
      oneOf:
      - $ref: '#/components/schemas/ExportedPublicKeyCredential'
      - $ref: '#/components/schemas/ExportedPasswordCredential'
      - $ref: '#/components/schemas/ExportedTOTPCredential'
      discriminator:
        propertyName: type
        mapping:
          public-key: '#/components/schemas/ExportedPublicKeyCredential'
          password: '#/components/schemas/ExportedPasswordCredential'
          totp: '#/components/schemas/ExportedTOTPCredential'
    ExportedTOTPCredential:
      type: object
      allOf:
      - $ref: '#/components/schemas/ExportedCredentialBase'
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/CredentialType'
          params:
            $ref: '#/components/schemas/ExportedTOTPCredentialParams'
          label:
            type: string
        required:
        - type
        - params
    TOTPCredential:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CredentialType'
        params:
          $ref: '#/components/schemas/TOTPCredentialParams'
        label:
          type: string
      required:
      - type
      - params
    PersonHandleType:
      type: string
      enum:
      - email_address
      - phone_number
      - username
      example: email_address
    APICursorPagination:
      type: object
      required:
      - limit
      - cursor
      - total_count
      properties:
        limit:
          type: integer
        cursor:
          type: string
        total_count:
          type: integer
          format: int64
    CredentialType:
      type: string
      description: The type of the credential
      enum:
      - public-key
      - password
      - totp
    PublicKeyCredential:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CredentialType'
        params:
          $ref: '#/components/schemas/PublicKeyCredentialParams'
        label:
          type: string
      required:
      - type
      - params
    ExportedTOTPCredentialParams:
      type: object
      required:
      - recovery_codes_total
      - recovery_codes_unused
      properties:
        recovery_codes_total:
          type: integer
          minimum: 0
          description: The total number of recovery codes originally issued to the given person.
        recovery_codes_unused:
          type: integer
          minimum: 0
          description: The total number of recovery codes still unused by the given person.
    ExportedPasswordCredential:
      type: object
      allOf:
      - $ref: '#/components/schemas/ExportedCredentialBase'
      - $ref: '#/components/schemas/PasswordCredential'
    PasswordRotatePostResp:
      type: object
      properties:
        new_password:
          type: string
    APIResponseError:
      type: object
      properties:
        httpcode:
          type: integer
        message:
          type: string
    ExportedCredentialBase:
      type: object
      properties:
        id:
          type: string
          description: The ID of the credential
        last_used:
          type: string
          format: date-time
          description: The time when the credential was last used to authenticate successfully
      required:
      - id
    APIMeta:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/APIPagination'
        cursor_pagination:
          $ref: '#/components/schemas/APICursorPagination'
    ExportedPublicKeyCredential:
      type: object
      allOf:
      - $ref: '#/components/schemas/ExportedCredentialBase'
      - $ref: '#/components/schemas/PublicKeyCredential'
    Credential:
      type: object
      oneOf:
      - $ref: '#/components/schemas/PublicKeyCredential'
      - $ref: '#/components/schemas/PasswordCredential'
      - $ref: '#/components/schemas/TOTPCredential'
      discriminator:
        propertyName: type
        mapping:
          public-key: '#/components/schemas/PublicKeyCredential'
          password: '#/components/schemas/PasswordCredential'
          totp: '#/components/schemas/TOTPCredential'
  parameters:
    OrgIDHeader:
      name: SlashID-OrgID
      in: header
      schema:
        type: string
      required: true
      description: The organization ID
      example: af5fbd30-7ce7-4548-8b30-4cd59cb2aba1
    CredentialIDPathParam:
      name: credential_id
      description: The person's credential ID
      example: 903c1ff9-f2cc-435c-b242-9d8a690fcf0a
      in: path
      required: true
      schema:
        type: string
    PersonIDPathParam:
      name: person_id
      description: The person ID
      example: 903c1ff9-f2cc-435c-b242-9d8a690fcf0a
      in: path
      required: true
      schema:
        type: string
  responses:
    NoContent:
      description: No content
    NotFound:
      description: Not Found
      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'
    Accepted:
      description: Accepted - Request was accepted and will be processed in the background
  securitySchemes:
    ApiKeyAuth:
      description: Authorizes the request with the organization's API Key.
      x-svc-um-api: true
      type: apiKey
      in: header
      name: SlashID-API-Key
    OAuth2ClientIdSecret:
      description: Authorizes the request with a client ID/client secret pair
      type: http
      scheme: basic
    OAuth2AccessTokenBearer:
      description: Authorizes the request with an Access Token for the current user.
      type: http
      scheme: bearer
      bearerFormat: opaque