swagger: '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. These API reference documents, along with client software libraries, are generated automatically from an OpenAPI 2.0 ("Swagger") definition file. ## Introduction A higher-level introduction to the API, as well as a description of the fatcat data model, are available in ["The Fatcat Guide"](https://guide.fatcat.wiki/). The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html) section demonstrating end-to-end tasks like creating entities as part of editgroups, or safely merging duplicate entities. ### Expectations and Best Practices A test/staging QA API instance of fatcat is available at . The database backing this instance is separate from the production interface, and is periodically rebuilt from snapshots of the full production database, meaning that edits on the QA server will *NOT* persist, and that semantics like the changelog index monotonically increasing *MAY* be broken. Developers are expexcted to test their scripts and tools against the QA instance before running against production. NOTE: as of Spring 2021, the QA server is temporarily unavailable. Fatcat is made available as a gratis (no cost) and libre (freedom preserving) service to the public, with limited funding and resources. We welcome new and unforeseen uses and contributions, but may need to impose restrictions (like rate-limits) to keep the service functional for other users, and in extreme cases reserve the option to block accounts and IP ranges if necessary to keep the service operational. The Internet Archive owns and operates it''s own server equipment and data centers, and operations are optimized for low-cost, not high-availability. Users and partners should expect some downtime on the fatcat API, on the order of hours a month. Periodic metadata exports are available for batch processing, and database snapshots can be used to create locally-hosted mirrors of the service for more intensive and reliable querying. ### Other Nitty Gritties Cross-origin requests are allowed for the API service, to enable third parties to build in-browser applications. A metadata search service is available at . The API is currently the raw elasticsearch API, with only GET (read) requests allowed. This public service is experimental and may be removed or limited in the future. ## Authentication The API allows basic read-only "GET" HTTP requests with no authentication. Proposing changes to the metadata, or other mutating requests ("PUT", "POST", "DELETE") all require authentication, and some operations require additional account permissions. End-user account creation and login happens through the web interface. From a logged-in editor profile page, you can generate a API token. Tokens are "macaroons", similar to JWT tokens, and are used for all API authentication. The web interface includes macaroons in browser cookies and passes them through to the API to authenticate editor actions. ' 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' host: api.fatcat.wiki basePath: /v0 schemes: - https consumes: - application/json produces: - application/json 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: [] parameters: - name: oidc_params in: body required: true schema: $ref: '#/definitions/auth_oidc' responses: 401: description: Not Authorized schema: $ref: '#/definitions/error_response' headers: WWW_Authenticate: type: string 403: description: Forbidden schema: $ref: '#/definitions/error_response' 200: description: Found schema: $ref: '#/definitions/auth_oidc_result' 201: description: Created schema: $ref: '#/definitions/auth_oidc_result' 400: description: Bad Request schema: $ref: '#/definitions/error_response' 409: description: Conflict schema: $ref: '#/definitions/error_response' 500: description: Generic Error schema: $ref: '#/definitions/error_response' /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 type: string responses: 401: description: Not Authorized schema: $ref: '#/definitions/error_response' headers: WWW_Authenticate: type: string 403: description: Forbidden schema: $ref: '#/definitions/error_response' 200: description: Success schema: $ref: '#/definitions/success' 400: description: Bad Request schema: $ref: '#/definitions/error_response' 500: description: Generic Error schema: $ref: '#/definitions/error_response' /auth/token/{editor_id}: parameters: - name: editor_id in: path type: string required: true 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 type: integer required: false description: How long API token should be valid for (in seconds) responses: 401: description: Not Authorized schema: $ref: '#/definitions/error_response' headers: WWW_Authenticate: type: string 403: description: Forbidden schema: $ref: '#/definitions/error_response' 200: description: Success schema: $ref: '#/definitions/auth_token_result' 400: description: Bad Request schema: $ref: '#/definitions/error_response' 500: description: Generic Error schema: $ref: '#/definitions/error_response' definitions: auth_oidc_result: type: object required: - editor - token properties: editor: $ref: '#/definitions/editor' token: type: string example: AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug= 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 success: type: object required: - success - message properties: success: type: boolean example: true message: type: string example: The computers did the thing successfully! 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). ' 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 securityDefinitions: 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: '#/definitions/error_response' headers: WWW_Authenticate: type: string 403: description: Forbidden schema: $ref: '#/definitions/error_response' x-entity-responses: 400: description: Bad Request schema: $ref: '#/definitions/error_response' 404: description: Not Found schema: $ref: '#/definitions/error_response' 500: description: Generic Error schema: $ref: '#/definitions/error_response'