Fatcat Auth API

openapi: 3.2.0
info:
  title: fatcat Auth API
  version: 0.5.0
  description: 'Fatcat is a scalable, versioned, API-oriented catalog of bibliographic

    entities and file metadata.'
  termsOfService: https://guide.fatcat.wiki/policies.html
  contact:
    name: Internet Archive Web Group
    email: webservices@archive.org
    url: https://fatcat.wiki
  x-logo:
    url: https://fatcat.wiki/static/paper_man_confused.gif
    altText: Confused Papers Man (Logo)
    backgroundColor: '#FFFFFF'
servers:
- url: https://api.fatcat.wiki/v0
tags:
- name: Auth
  x-displayName: Auth Methods
  description: 'Helper methods and internal APIs for editor authentication. # TAGLINE'
paths:
  /auth/oidc:
    post:
      operationId: auth_oidc
      tags:
      - Auth
      description: 'Login or create editor account using OIDC metadata (internal method).


        This method is used by privileged front-end tools (like the web

        interface service) to process editor logins using OpenID Connect (OIDC)

        and/or OAuth. Most accounts (including tool and bot accounts) do not

        have sufficient privileges to call this method, which requires the

        `admin` role.


        The method returns an API token; the HTTP status code indicates whether

        an existing account was logged in, or a new account was created.'
      security:
      - Bearer: []
      responses:
        401:
          description: Not Authorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_oidc_result'
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_oidc_result'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        409:
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/auth_oidc'
        required: true
      summary: Auth oidc
      x-summary-source: derived
  /auth/check:
    get:
      operationId: auth_check
      tags:
      - Auth
      description: 'Verify that authentication (API token) is working as expected. The

        optional `role` parameter can be used to verify that the current

        account (editor) has permissions for the given role.'
      security:
      - Bearer: []
      parameters:
      - name: role
        in: query
        required: false
        schema:
          type: string
      responses:
        401:
          description: Not Authorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      summary: Auth check
      x-summary-source: derived
  /auth/token/{editor_id}:
    parameters:
    - name: editor_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: create_auth_token
      tags:
      - Auth
      description: 'Generate a new auth token for a given editor (internal method).


        This method is used by the web interface to generate API tokens for

        users. It can not be called by editors (human or bot) to generate new

        tokens for themselves, at least at this time.'
      security:
      - Bearer: []
      parameters:
      - name: duration_seconds
        in: query
        required: false
        description: How long API token should be valid for (in seconds)
        schema:
          type: integer
      responses:
        401:
          description: Not Authorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_token_result'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      summary: Create auth token
      x-summary-source: derived
components:
  schemas:
    editor:
      type: object
      required:
      - username
      properties:
        editor_id:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'Fatcat identifier for the editor. Can not be changed.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        username:
          type: string
          example: zerocool93
          description: 'Username/handle (short slug-like string) to identify this editor. May

            be changed at any time by the editor; use the `editor_id` as a

            persistend identifier.

            '
        is_admin:
          type: boolean
          example: false
          description: 'Whether this editor has the `admin` role.

            '
        is_bot:
          type: boolean
          example: false
          description: 'Whether this editor is a bot (as opposed to a human making manual

            edits)

            '
        is_active:
          type: boolean
          example: true
          description: 'Whether this editor''s account is enabled (if not API tokens and web

            logins will not work).

            '
    success:
      type: object
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: The computers did the thing successfully!
    auth_token_result:
      type: object
      required:
      - token
      properties:
        token:
          type: string
          example: AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=
    error_response:
      type: object
      required:
      - success
      - error
      - message
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: unexpected-thing
        message:
          type: string
          example: A really confusing, totally unexpected thing happened
    auth_oidc:
      type: object
      required:
      - provider
      - sub
      - iss
      - preferred_username
      properties:
        provider:
          type: string
          example: orcid
          description: 'Fatcat-specific short name (slug) for remote service being used for

            authentication.

            '
        sub:
          type: string
          description: '`SUB` from OIDC protocol. Usually a URL.'
          example: https://orcid.org
        iss:
          type: string
          description: '`ISS` from OIDC protocol. Usually a stable account username, number, or identifier.'
          example: 0000-0002-8593-9468
        preferred_username:
          type: string
          description: 'What it sounds like; returned by OIDC, and used as a hint when

            creating new editor accounts. Fatcat usernames are usually this

            string with the `provider` slug as a suffix, though some munging may

            occur.

            '
          example: bnewbold
    auth_oidc_result:
      type: object
      required:
      - editor
      - token
      properties:
        editor:
          $ref: '#/components/schemas/editor'
        token:
          type: string
          example: AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header
      description: "The only current API authentication mechanism is HTTP bearer\nauthentication using the `Authorization` HTTP header. The header should\nbe formatted as the string \"Bearer\", then a space, then API token (in the\nusual base64 string encoding).\n\nAn example HTTP request would look on the wire like:\n\n    GET /v0/auth/check HTTP/1.1\n    Accept: */*\n    Accept-Encoding: gzip, deflate\n    Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\n    Connection: keep-alive\n    Host: api.qa.fatcat.wiki\n    User-Agent: HTTPie/0.9.8\n\nHeaders can be passed on the command line using `http` (HTTPie) like:\n\n    http get https://api.qa.fatcat.wiki/v0/auth/check Authorization:\"Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\"\n\nOr with `curl`:\n\n    curl -H \"Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\" https://qa.fatcat.wiki/v0/auth/check\n"
x-servers:
- url: https://api.fatcat.wiki/v0
  description: Production Server
- url: https://api.qa.fatcat.wiki/v0
  description: QA Server
x-tagGroups:
- name: Entities
  tags:
  - containers
  - creators
  - files
  - filesets
  - webcaptures
  - releases
  - works
- name: Editing
  tags:
  - editors
  - editgroups
  - changelog
- name: Other
  tags:
  - auth
x-fatcat-ident:
  type: string
  pattern: '[a-zA-Z2-7]{26}'
  minLength: 26
  maxLength: 26
  description: base32-encoded unique identifier
x-fatcat-ident-example:
  example: q3nouwy3nnbsvo3h5klxsx4a7y
x-fatcat-uuid:
  type: string
  pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
  minLength: 36
  maxLength: 36
  description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
x-fatcat-uuid-example:
  example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
x-issn:
  type: string
  pattern: \d{4}-\d{3}[0-9X]
  minLength: 9
  maxLength: 9
x-issn-example:
  example: 1234-5678
x-orcid:
  type: string
  pattern: \d{4}-\d{4}-\d{4}-\d{3}[\dX]
  minLength: 19
  maxLength: 19
  description: ORCiD (https://orcid.org) identifier
x-orcid-example:
  example: 0000-0002-1825-0097
x-md5:
  type: string
  pattern: '[a-f0-9]{32}'
  minLength: 32
  maxLength: 32
  description: MD5 hash of data, in hex encoding
x-md5-example:
  example: 1b39813549077b2347c0f370c3864b40
x-sha1:
  type: string
  pattern: '[a-f0-9]{40}'
  minLength: 40
  maxLength: 40
  description: SHA-1 hash of data, in hex encoding
x-sha1-example:
  example: e9dd75237c94b209dc3ccd52722de6931a310ba3
x-sha256:
  type: string
  pattern: '[a-f0-9]{64}'
  minLength: 64
  maxLength: 64
  description: SHA-256 hash of data, in hex encoding
x-sha256-example:
  example: cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452
x-entity-props:
  state:
    type: string
    enum:
    - wip
    - active
    - redirect
    - deleted
    example: active
  ident:
    type: string
    pattern: '[a-zA-Z2-7]{26}'
    minLength: 26
    maxLength: 26
    description: base32-encoded unique identifier
    example: q3nouwy3nnbsvo3h5klxsx4a7y
  revision:
    type: string
    pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
    minLength: 36
    maxLength: 36
    description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
    example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
  redirect:
    type: string
    pattern: '[a-zA-Z2-7]{26}'
    minLength: 26
    maxLength: 26
    description: base32-encoded unique identifier
    example: q3nouwy3nnbsvo3h5klxsx4a7y
  extra:
    type: object
    description: 'Free-form JSON metadata that will be stored with the other entity

      metadata. See guide for (unenforced) schema conventions.

      '
    additionalProperties: {}
  edit_extra:
    type: object
    description: 'Free-form JSON metadata that will be stored with specific entity edits

      (eg, creation/update/delete).

      '
    additionalProperties: {}
x-auth-responses:
  401:
    description: Not Authorized
    schema:
      $ref: '#/components/schemas/error_response'
    headers:
      WWW_Authenticate:
        type: string
  403:
    description: Forbidden
    schema:
      $ref: '#/components/schemas/error_response'
x-entity-responses:
  400:
    description: Bad Request
    schema:
      $ref: '#/components/schemas/error_response'
  404:
    description: Not Found
    schema:
      $ref: '#/components/schemas/error_response'
  500:
    description: Generic Error
    schema:
      $ref: '#/components/schemas/error_response'