> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hanko.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Initialize a registration, authentication, or de-registration operation for the Hanko Authenticator.

# Create a request for the Hanko Authenticator

<Note>
  Remember the returned `id` — you'll need it to check the status of, validate, or cancel this operation.
</Note>


## OpenAPI

````yaml openapi-authenticator post /v1/uaf/requests
openapi: 3.0.0
info:
  contact:
    name: Support
    url: https://hanko.io
    email: info@hanko.io
  description: >
    With Hanko you are able to offer your users the security and convenience of

    password-less authentication. Get your website or app ready for a future

    without passwords. Head over to our website at [hanko.io](https://hanko.io)
    to

    learn more about the service or read our
    [documentation](https://docs.hanko.io).
  title: Hanko Service API
  version: 1.0.0
servers:
  - url: https://api.hanko.io
    description: Production environment
security:
  - ApiKeyAuth: []
tags:
  - name: routes
  - name: Hello Hanko
    description: Learn how to use this REST API
  - name: Web Authentication
    description: Authentication via W3C WebAuthentication
    externalDocs:
      url: https://hanko.io
  - name: Hanko Authenticator
    description: >-
      Authentication with the Hanko Authenticator and FIDO UAF (out-of-band
      style)
    externalDocs:
      url: https://hanko.io
  - name: Device Management
    description: Manage the Devices of your users
    externalDocs:
      url: https://hanko.io
externalDocs:
  description: Visit our documentation to learn more about the Hanko service and its APIs
  url: https://docs.hanko.io
paths:
  /v1/uaf/requests:
    post:
      tags:
        - Hanko Authenticator
      summary: Create a request for the Hanko Authenticator
      description: >
        Using this endpoint you initialize a new registration, authentication,
        or deregistration by creating a new operation. Be sure to indicate the
        requested type by setting the operation to the correct enum value.
        Remember the `id` to take actions regarding this operation.
      operationId: createUaf
      requestBody:
        $ref: '#/components/requestBodies/HankoCreateOperationRequest'
      responses:
        '200':
          $ref: '#/components/responses/HankoUafRequestWithLinks'
        '400':
          $ref: '#/components/responses/Default400Error'
        '401':
          $ref: '#/components/responses/Default401Error'
        '500':
          $ref: '#/components/responses/Default500Error'
components:
  requestBodies:
    HankoCreateOperationRequest:
      description: The description
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/models.CreateRequest'
  responses:
    HankoUafRequestWithLinks:
      description: >-
        The full Hanko request for an initialized authentication operation
        including links
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/models.HankoRequest'
      links:
        Validate:
          $ref: '#/components/links/Validate'
        Get:
          $ref: '#/components/links/Get'
        Cancel:
          $ref: '#/components/links/Cancel'
        QrCode:
          $ref: '#/components/links/QrCode'
    Default400Error:
      description: Bad request, the service could not process your request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HankoError'
          example:
            code: 400
            message: Bad Request
    Default401Error:
      description: You are not authenticated. Provide your credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HankoError'
          example:
            code: 401
            message: Unauthorized
    Default500Error:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HankoError'
          example:
            code: 500
            message: Internal Server Error
  schemas:
    models.CreateRequest:
      properties:
        operation:
          type: string
          enum:
            - AUTH
            - DEREG
            - REG
        username:
          type: string
        userId:
          type: string
        displayName:
          type: string
        clientData:
          $ref: '#/components/schemas/models.ClientData'
        transaction:
          type: string
        deviceIds:
          type: array
          items:
            type: string
        authenticatorSelectionCriteria:
          $ref: '#/components/schemas/models.AuthenticatorSelectionCriteria'
        attestationConveyancePreference:
          type: string
          enum:
            - direct
            - indirect
            - none
        isSecondFactorOnly:
          type: boolean
      required:
        - operation
    models.HankoRequest:
      properties:
        id:
          type: string
        operation:
          type: string
          enum:
            - AUTH
            - DEREG
            - REG
        username:
          type: string
        userId:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - OK
            - FAILED
            - INVALIDATED
        createdAt:
          format: date-time
          type: string
        validUntil:
          format: date-time
          type: string
        relyingParty:
          $ref: '#/components/schemas/models.RelyingParty'
        clientData:
          $ref: '#/components/schemas/models.ClientData'
        location:
          $ref: '#/components/schemas/models.Location'
        links:
          type: array
          items:
            $ref: '#/components/schemas/models.Link'
        transaction:
          type: string
        request:
          type: string
        deviceID:
          type: string
        device:
          $ref: '#/components/schemas/models.RequestDevice'
        isSecondFactorOnly:
          type: boolean
        error:
          $ref: '#/components/schemas/models.RequestError'
      required:
        - id
        - operation
        - username
        - userId
        - status
        - createdAt
        - validUntil
        - relyingParty
        - links
        - request
        - deviceID
    HankoError:
      type: object
      description: An error object giving details about the origin of the error
      properties:
        code:
          type: integer
        message:
          type: string
    models.ClientData:
      properties:
        remoteAddress:
          type: string
        userAgent:
          type: string
    models.AuthenticatorSelectionCriteria:
      properties:
        authenticatorAttachment:
          type: string
          enum:
            - platform
            - cross-platform
        requireResidentKey:
          type: boolean
        userVerification:
          type: string
          enum:
            - required
            - preferred
            - discouraged
    models.RelyingParty:
      properties:
        id:
          type: string
        name:
          type: string
        appId:
          type: string
        icon:
          type: string
      required:
        - id
        - name
        - appId
        - icon
    models.Location:
      properties:
        country:
          type: string
        region:
          type: string
        city:
          type: string
      required:
        - country
        - region
        - city
    models.Link:
      properties:
        rel:
          type: string
        method:
          type: string
        href:
          type: string
      required:
        - rel
        - method
        - href
    models.RequestDevice:
      properties:
        deviceId:
          type: string
        keyName:
          type: string
    models.RequestError:
      properties:
        code:
          type: integer
          format: int32
        reason:
          type: string
      required:
        - code
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        This API uses `Authorization: secret <api_key>`
        rather than the standard `Bearer` scheme.

````