openapi: 3.0.0
info:
  title: Auth0 Authentication actions device-credentials API
  description: Auth0 Authentication API. Endpoints for authentication and authorization using OpenID Connect, OAuth 2.0, SAML, WS-Federation, and Passwordless flows.
  version: 1.0.0
servers:
- url: '{auth0_domain}'
  description: The Authentication API is served over HTTPS.
  variables:
    auth0_domain:
      description: Auth0 domain
      default: https://demo.us.auth0.com
tags:
- name: device-credentials
paths:
  /device-credentials:
    get:
      summary: Retrieve Device Credentials
      description: 'Retrieve device credential information (<code>public_key</code>, <code>refresh_token</code>, or <code>rotating_refresh_token</code>) associated with a specific user.

        '
      tags:
      - device-credentials
      parameters:
      - name: page
        in: query
        description: Page index of the results to return. First page is 0.
        schema:
          type: integer
          minimum: 0
      - name: per_page
        in: query
        description: Number of results per page.  There is a maximum of 1000 results allowed from this endpoint.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: include_totals
        in: query
        description: Return results inside an object that contains the total result count (true) or as a direct array of results (false, default).
        schema:
          type: boolean
      - name: fields
        in: query
        description: Comma-separated list of fields to include or exclude (based on value provided for include_fields) in the result. Leave empty to retrieve all fields.
        schema:
          type: string
          pattern: ^((device_name)|(id)|(device_id)|(type)|(user_id)|(client_id))(,((device_name)|(id)|(device_id)|(type)|(user_id)|(client_id)))*$
      - name: include_fields
        in: query
        description: Whether specified fields are to be included (true) or excluded (false).
        schema:
          type: boolean
      - name: user_id
        in: query
        description: user_id of the devices to retrieve.
        schema:
          type: string
      - name: client_id
        in: query
        description: client_id of the devices to retrieve.
        schema:
          type: string
      - name: type
        in: query
        description: Type of credentials to retrieve. Must be `public_key`, `refresh_token` or `rotating_refresh_token`. The property will default to `refresh_token` when paging is requested
        schema:
          $ref: '#/components/schemas/DeviceCredentialTypeEnum'
      responses:
        '200':
          description: Device credentials successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDeviceCredentialsResponseContent'
        '400':
          description: Invalid request query string. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
          x-description-3: Username is malformed, try with '{connection}\{email_or_username}'
          x-description-4: Bad username or password.
        '403':
          description: User to be acted on does not match subject in bearer token.
          x-description-1: 'Insufficient scope, expected any of: read:device_credentials'
          x-description-2: Cannot retrieve device credentials for that user.
          x-description-3: Cannot retrieve device credentials for that client.
          x-description-4: Must provide client_id parameter.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_device-credentials
      x-release-lifecycle: GA
      x-operation-name: list
      x-operation-request-parameters-name: ListDeviceCredentialsRequestParameters
      x-operation-group: deviceCredentials
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:device_credentials
    post:
      summary: Create a Device Public Key Credential
      description: 'Create a device credential public key to manage refresh token rotation for a given <code>user_id</code>. Device Credentials APIs are designed for ad-hoc administrative use only and paging is by default enabled for GET requests.


        When refresh token rotation is enabled, the endpoint becomes consistent. For more information, read <a href="https://auth0.com/docs/get-started/tenant-settings/signing-keys"> Signing Keys</a>.

        '
      tags:
      - device-credentials
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePublicKeyDeviceCredentialRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreatePublicKeyDeviceCredentialRequestContent'
      responses:
        '201':
          description: Device credentials successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePublicKeyDeviceCredentialResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
          x-description-2: Username is malformed, try with "{connection}\{email_or_username}".
          x-description-3: Bad username or password.
        '403':
          description: Cannot create device credentials for that user.
          x-description-1: Cannot create device credentials for that client.
          x-description-2: 'Insufficient scope; expected any of: create:current_user_device_credentials.'
        '409':
          description: A public key already exists for the device.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: post_device-credentials
      x-release-lifecycle: GA
      x-operation-name: createPublicKey
      x-operation-group: deviceCredentials
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - create:current_user_device_credentials
  /device-credentials/{id}:
    delete:
      summary: Delete a Device Credential
      description: Permanently delete a device credential (such as a refresh token or public key) with the given ID.
      tags:
      - device-credentials
      parameters:
      - name: id
        in: path
        description: ID of the credential to delete.
        required: true
        schema:
          type: string
          pattern: ^dcr_[A-Za-z0-9]{16}$
      responses:
        '204':
          description: Device credentials successfully deleted.
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
          x-description-3: Username is malformed, try with "{connection}\{email_or_username}".
          x-description-4: Bad username or password.
        '403':
          description: 'Insufficient scope; expected any of: delete:device_credentials, update:current_user, delete:current_user_device_credentials.'
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: delete_device-credentials_by_id
      x-release-lifecycle: GA
      x-operation-name: delete
      x-operation-group: deviceCredentials
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - delete:device_credentials
        - delete:current_user_device_credentials
components:
  schemas:
    DeviceCredentialPublicKeyTypeEnum:
      type: string
      description: Type of credential. Must be `public_key`.
      enum:
      - public_key
    CreatePublicKeyDeviceCredentialResponseContent:
      type: object
      additionalProperties: true
      required:
      - id
      properties:
        id:
          type: string
          description: The credential's identifier
          default: dcr_0000000000000001
    ListDeviceCredentialsOffsetPaginatedResponseContent:
      type: object
      additionalProperties: false
      properties:
        start:
          type: number
        limit:
          type: number
        total:
          type: number
        device_credentials:
          type: array
          items:
            $ref: '#/components/schemas/DeviceCredential'
    DeviceCredential:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: ID of this device.
          default: dcr_0000000000000001
        device_name:
          type: string
          description: User agent for this device
          default: iPhone Mobile Safari UI/WKWebView
        device_id:
          type: string
          description: 'Unique identifier for the device. NOTE: This field is generally not populated for refresh_tokens and rotating_refresh_tokens'
          default: 550e8400-e29b-41d4-a716-446655440000
        type:
          $ref: '#/components/schemas/DeviceCredentialTypeEnum'
          description: Type of credential. Can be `public_key`, `refresh_token`, or `rotating_refresh_token`.
        user_id:
          type: string
          description: user_id this credential is associated with.
          default: usr_5457edea1b8f33391a000004
        client_id:
          type: string
          description: client_id of the client (application) this credential is for.
          default: AaiyAPdpYdesoKnqjj8HJqRn4T5titww
    DeviceCredentialTypeEnum:
      type: string
      enum:
      - public_key
      - refresh_token
      - rotating_refresh_token
      description: Type of credentials to retrieve. Must be `public_key`, `refresh_token` or `rotating_refresh_token`. The property will default to `refresh_token` when paging is requested
    CreatePublicKeyDeviceCredentialRequestContent:
      type: object
      additionalProperties: true
      required:
      - device_name
      - type
      - value
      - device_id
      properties:
        device_name:
          type: string
          description: Name for this device easily recognized by owner.
          minLength: 1
        type:
          $ref: '#/components/schemas/DeviceCredentialPublicKeyTypeEnum'
        value:
          type: string
          description: Base64 encoded string containing the credential.
          minLength: 1
        device_id:
          type: string
          description: Unique identifier for the device. Recommend using <a href="http://developer.android.com/reference/android/provider/Settings.Secure.html#ANDROID_ID">Android_ID</a> on Android and <a href="https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIDevice_Class/index.html#//apple_ref/occ/instp/UIDevice/identifierForVendor">identifierForVendor</a>.
          maxLength: 36
          pattern: ^[-A-Fa-f0-9]+$
        client_id:
          type: string
          description: client_id of the client (application) this credential is for.
          format: client-id
    ListDeviceCredentialsResponseContent:
      oneOf:
      - type: array
        items:
          $ref: '#/components/schemas/DeviceCredential'
      - $ref: '#/components/schemas/ListDeviceCredentialsOffsetPaginatedResponseContent'