openapi: 3.0.0
info:
  contact:
    email: hello@authentiq.com
    name: Authentiq team
    url: 'http://authentiq.io/support'
  description: 'Strong authentication, without the passwords.'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  termsOfService: 'http://authentiq.com/terms/'
  title: Authentiq
  version: '6'
  x-apisguru-categories:
    - security
  x-logo:
    backgroundColor: '#F26641'
    url: >-
      https://api.apis.guru/v2/cache/logo/https_www.authentiq.com_theme_images_authentiq-logo-a-inverse.svg
  x-origin:
    - format: swagger
      url: >-
        https://raw.githubusercontent.com/AuthentiqID/authentiq-docs/master/docs/swagger/issuer.yaml
      version: '2.0'
  x-preferred: true
  x-providerName: 6-dot-authentiqio.appspot.com
paths:
  /key:
    delete:
      description: |
        Revoke an Authentiq ID using email & phone.

        If called with `email` and `phone` only, a verification code 
        will be sent by email. Do a second call adding `code` to 
        complete the revocation.
      operationId: key_revoke_nosecret
      parameters:
        - description: primary email associated to Key (ID)
          in: query
          name: email
          required: true
          schema:
            type: string
        - description: 'primary phone number, international representation'
          in: query
          name: phone
          required: true
          schema:
            type: string
        - description: verification code sent by email
          in: query
          name: code
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully deleted
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: pending or done
                    type: string
                type: object
        '401':
          description: Authentication error `auth-error`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown key `unknown-key`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Confirm with code sent `confirm-first`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - key
        - delete
    post:
      description: |
        Register a new ID `JWT(sub, devtoken)`

        v5: `JWT(sub, pk, devtoken, ...)`

        See: https://github.com/skion/authentiq/wiki/JWT-Examples
      operationId: key_register
      responses:
        '201':
          description: Successfully registered
          content:
            application/json:
              schema:
                properties:
                  secret:
                    description: revoke key
                    type: string
                  status:
                    description: registered
                    type: string
                type: object
        '409':
          description: Key already registered `duplicate-key`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - key
        - post
      requestBody:
        $ref: '#/components/requestBodies/AuthentiqID'
  '/key/{PK}':
    delete:
      description: Revoke an Identity (Key) with a revocation secret
      operationId: key_revoke
      parameters:
        - $ref: '#/components/parameters/PK'
        - description: revokation secret
          in: query
          name: secret
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: done
                    type: string
                type: object
        '401':
          description: Key not found / wrong code `auth-error`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown key `unknown-key`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - key
        - delete
    get:
      description: |
        Get public details of an Authentiq ID.
      parameters:
        - $ref: '#/components/parameters/PK'
      responses:
        '200':
          description: Successfully retrieved
          content:
            application/json:
              schema:
                properties:
                  since:
                    format: date-time
                    type: string
                  status:
                    type: string
                  sub:
                    description: base64safe encoded public signing key
                    type: string
                title: JWT
                type: object
        '404':
          description: Unknown key `unknown-key`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Key is revoked (gone). `revoked-key`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - key
        - get
    head:
      description: |
        HEAD info on Authentiq ID
      parameters:
        - $ref: '#/components/parameters/PK'
      responses:
        '200':
          description: Key exists
        '404':
          description: Unknown key `unknown-key`
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Key is revoked `revoked-key`
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - key
        - head
    post:
      description: |
        update properties of an Authentiq ID.
        (not operational in v4; use PUT for now)

        v5: POST issuer-signed email & phone scopes in
        a self-signed JWT

        See: https://github.com/skion/authentiq/wiki/JWT-Examples
      operationId: key_update
      parameters:
        - $ref: '#/components/parameters/PK'
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: confirmed
                    type: string
                type: object
        '404':
          description: Unknown key `unknown-key`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - key
        - post
      requestBody:
        $ref: '#/components/requestBodies/AuthentiqID'
    put:
      description: |
        Update Authentiq ID by replacing the object.

        v4: `JWT(sub,email,phone)` to bind email/phone hash; 

        v5: POST issuer-signed email & phone scopes
        and PUT to update registration `JWT(sub, pk, devtoken, ...)`

        See: https://github.com/skion/authentiq/wiki/JWT-Examples
      operationId: key_bind
      parameters:
        - $ref: '#/components/parameters/PK'
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: confirmed
                    type: string
                type: object
        '404':
          description: Unknown key `unknown-key`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Already bound to another key `duplicate-hash`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - key
        - put
      requestBody:
        $ref: '#/components/requestBodies/AuthentiqID'
  /login:
    post:
      description: |
        push sign-in request
        See: https://github.com/skion/authentiq/wiki/JWT-Examples
      operationId: push_login_request
      parameters:
        - description: URI App will connect to
          in: query
          name: callback
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: sent
                    type: string
                type: object
        '401':
          description: >-
            Unauthorized for this callback audience `aud-error` or JWT should be
            self-signed `auth-error`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - login
        - post
      requestBody:
        content:
          application/jwt:
            schema:
              $ref: '#/components/schemas/PushToken'
        description: Push Token.
        required: true
  /scope:
    post:
      description: |
        scope verification request
        See: https://github.com/skion/authentiq/wiki/JWT-Examples
      operationId: sign_request
      parameters:
        - description: 'test only mode, using test issuer'
          in: query
          name: test
          required: false
          schema:
            type: integer
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  job:
                    description: 20-character ID
                    type: string
                  status:
                    description: waiting
                    type: string
                type: object
        '429':
          description: Too Many Requests on same address / number `rate-limit`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - scope
        - post
      requestBody:
        content:
          application/jwt:
            schema:
              $ref: '#/components/schemas/Claims'
        description: Claims of scope
        required: true
  '/scope/{job}':
    delete:
      description: delete a verification job
      operationId: sign_delete
      parameters:
        - $ref: '#/components/parameters/JobID'
      responses:
        '200':
          description: Successfully deleted
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: done
                    type: string
                type: object
        '404':
          description: Job not found `unknown-job`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - scope
        - delete
    get:
      description: get the status / current content of a verification job
      operationId: sign_retrieve
      parameters:
        - $ref: '#/components/parameters/JobID'
      responses:
        '200':
          description: Successful response (JWT)
          content:
            application/json:
              schema:
                properties:
                  exp:
                    type: integer
                  field:
                    type: string
                  sub:
                    description: base64safe encoded public signing key
                    type: string
                title: JWT
                type: object
            application/jwt:
              schema:
                properties:
                  exp:
                    type: integer
                  field:
                    type: string
                  sub:
                    description: base64safe encoded public signing key
                    type: string
                title: JWT
                type: object
        '204':
          description: 'Confirmed, waiting for signing'
        '404':
          description: Job not found `unknown-job`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/jwt:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - scope
        - get
    head:
      description: HEAD to get the status of a verification job
      operationId: sign_retrieve_head
      parameters:
        - $ref: '#/components/parameters/JobID'
      responses:
        '200':
          description: Confirmed and signed
        '204':
          description: 'Confirmed, waiting for signing'
        '404':
          description: Job not found `unknown-job`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - scope
        - head
    post:
      description: this is a scope confirmation
      operationId: sign_confirm
      parameters:
        - $ref: '#/components/parameters/JobID'
      responses:
        '202':
          description: Successfully confirmed
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: confirmed
                    type: string
                type: object
        '401':
          description: Confirmation error `auth-error`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Job not found `unknown-job`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: JWT POSTed to scope `not-supported`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - scope
        - post
    put:
      description: |
        authority updates a JWT with its signature
        See: https://github.com/skion/authentiq/wiki/JWT-Examples
      operationId: sign_update
      parameters:
        - $ref: '#/components/parameters/JobID'
      responses:
        '200':
          description: Successfully updated
          content:
            application/jwt:
              schema:
                properties:
                  jwt:
                    description: result is JWT or JSON??
                    type: string
                  status:
                    description: ready
                    type: string
                type: object
        '404':
          description: Job not found `unknown-job`
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Job not confirmed yet `confirm-first`
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
      tags:
        - scope
        - put
servers:
  - url: 'https://6-dot-authentiqio.appspot.com/'
components:
  parameters:
    JobID:
      description: Job ID (20 chars)
      in: path
      name: job
      required: true
      schema:
        type: string
    PK:
      description: Public Signing Key - Authentiq ID (43 chars)
      in: path
      name: PK
      required: true
      schema:
        type: string
  responses:
    ErrorResponse:
      description: Error response
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
  requestBodies:
    AuthentiqID:
      content:
        application/jwt:
          schema:
            $ref: '#/components/schemas/AuthentiqID'
      description: Authentiq ID to register
      required: true
  schemas:
    AuthentiqID:
      description: |
        Authentiq ID in JWT format, self-signed.
      properties:
        devtoken:
          description: device token for push messages
          type: string
        sub:
          description: UUID and public signing key
          type: string
      required:
        - sub
    Claims:
      description: |
        Claim in JWT format, self- or issuer-signed. 
      properties:
        email:
          description: ''
          type: string
        phone:
          description: ''
          type: string
        scope:
          description: claim scope
          type: string
        sub:
          description: UUID
          type: string
        type:
          description: ''
          type: string
      required:
        - sub
        - scope
    Error:
      properties:
        detail:
          type: string
        error:
          type: integer
        title:
          type: string
        type:
          description: unique uri for this error
          type: string
      required:
        - error
    PushToken:
      description: |
        PushToken in JWT format, self-signed. 
      properties:
        aud:
          description: audience (URI)
          type: string
        exp:
          type: integer
        iat:
          type: integer
        iss:
          description: issuer (URI)
          type: string
        nbf:
          type: integer
        sub:
          description: UUID and public signing key
          type: string
      required:
        - sub
        - iss
        - aud