openapi: 3.0.1
info:
  title: SlashID Groups Person handles 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 handles
paths:
  /persons/{person_id}/handles:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    post:
      operationId: PostPersonsPersonIdHandles
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Person handles
      summary: Add handles to a person
      description: Add one or more handles to an existing person linked to your organization.
      requestBody:
        description: The person handles POST request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonHandlesReq'
            examples:
              personHandlesExample:
                $ref: '#/components/examples/personHandlesExample'
        required: true
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      operationId: GetPersonsPersonIdHandles
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin,member,impersonator
      tags:
      - Person handles
      summary: Get handles for a person
      description: Retrieve the list of handles associated with an existing person
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIResponseBase'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/PersonHandlesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /persons/{person_id}/handles/{handle}:
    parameters:
    - $ref: '#/components/parameters/PersonIDPathParam'
    - $ref: '#/components/parameters/OrgIDHeader'
    - $ref: '#/components/parameters/HandlePathParam'
    delete:
      operationId: DeletePersonsPersonIdHandlesHandle
      x-rbac-enabled: true
      x-rbac-allowed-groups: admin
      tags:
      - Person handles
      summary: Delete a handle from a person
      description: Remove a handle associated with an existing person
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PersonHandlesReq:
      type: array
      items:
        $ref: '#/components/schemas/PersonHandle'
    PersonHandle:
      required:
      - type
      - value
      type: object
      properties:
        type:
          $ref: '#/components/schemas/PersonHandleType'
        value:
          type: string
          example: user@user.com
    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
    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
    APIResponseError:
      type: object
      properties:
        httpcode:
          type: integer
        message:
          type: string
    PersonHandlesResponse:
      type: array
      items:
        $ref: '#/components/schemas/PersonHandle'
    APIMeta:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/APIPagination'
        cursor_pagination:
          $ref: '#/components/schemas/APICursorPagination'
  examples:
    usernameHandleExample:
      value: username:john_smith
    emailHandleExample:
      value: email_address:user@user.com
    personHandlesExample:
      value:
      - type: email_address
        value: user@user.com
      - type: phone_number
        value: '+13475043201'
      - type: username
        value: john_smith
      summary: Example person handles
    phoneNumberHandleExample:
      value: phone_number:+13475043201
  parameters:
    OrgIDHeader:
      name: SlashID-OrgID
      in: header
      schema:
        type: string
      required: true
      description: The organization ID
      example: af5fbd30-7ce7-4548-8b30-4cd59cb2aba1
    HandlePathParam:
      name: handle
      description: 'Handle in format [handle_type]:[handle]. Supported handle types are ''email_address'', ''phone_number'', and ''username''. This field should be URL-encoded.

        '
      in: path
      required: true
      schema:
        type: string
      examples:
        email_address:
          $ref: '#/components/examples/emailHandleExample'
        phone_number:
          $ref: '#/components/examples/phoneNumberHandleExample'
        username:
          $ref: '#/components/examples/usernameHandleExample'
    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'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponseBase'
  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