Verification Server Swagger Specs

Documentation of the admin and device APIs for the Verification Server

Admin API

swagger: '2.0'
info:
  description: "This is a summarized view of the GAEN Verification Server V1.5. We will expose the spec for issuing a verification code. Note This document is for a server implementing v1.5 of GAEN Verification Protocol."
  version: 1.5.0
  title: "GAEN Verification Server API"
  contact:
    email: "yonatan.meschede-krasa@pathcheck.org"
  license:
    name: Apache 2.0
    url: "https://github.com/google/exposure-notifications-verification-server/blob/main/LICENSE"
tags:
- name: "IssueCode"
  description: "Issuing verification codes"
  externalDocs:
    description: "Verification Certificate HMAC Flow Overview"
    url: "https://bit.ly/314qCXv"

paths:
  /issue:
    post:
      tags:
      - IssueCode
      summary: "Issues a new GAEN Verification Code"
      operationId: IssueCodeRequest
      description: "Creates and issues verification code for contact tracer to communicate to app user"
      externalDocs:
        description: "Reference for API implementation."
        url: "https://bit.ly/3g9JZ6l"
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: "IssueCode Request Body with option symptoms"
        schema:
          $ref: '#/definitions/IssueCodeRequest'
      - in: header
        name: X-API-KEY
        description: "Admin API key"
        type: string
      responses:
        200:
          description: "Response Object with a UUID and verification code"
          schema:
            $ref: '#/definitions/IssueCodeResponse'
        400:
          description: "Bad Request Error"
          schema:
            $ref: '#/definitions/IssueCodeErrorResponse'

definitions:
  IssueCodeRequest:
    type: object
    required:
    - testtype
    - symptomdate
    properties: 
      testtype: 
        type: string
        description: "Possible Covid Test Results Outcome"
        example: "confirmed"
        enum:
          - "confirmed"
          - "likely"
          - "negative"
      symptomdate: 
        type: string
        description: "ISO 8601 formatted date, YYYY-MM-DD."
        example: "2020-08-14"
  IssueCodeResponse:
    type: object
    properties: 
      uuid: 
        type: string
        format: uuid
      code: 
        type: string
        description: "Typically an 8 digit value. e.g. 12345678"
        example: "14819513"
      expiresAt: 
        type: string
        description: "RFC1123 string formatted timestamp, in UTC."
        example: "Fri, 14 Aug 2020 16:47:30 UTC"
      expiresAtTimestamp: 
        type: integer
        format: "int64"
        description: "Unix, seconds since the epoch. Still UTC."
        example: 1597423650
      error: 
        type: string
  IssueCodeErrorResponse:
    type: object
    properties:
      error:
        type: string
        example: "invalid test type"
        description: "Error message. e.g. Not Found"
      error_code: 
        type: string
        example: ""
        description: "Server error code."

host: "adminapi.gaen.extremesolution.com"
basePath: /api
schemes:
 - https

Device API

swagger: '2.0'
info:
  description: "This is a summarized view of the GAEN Verification Server V1.5. We will expose the spec for issuing a verification code. Note This document is for a server implementing v1.5 of GAEN Verification Protocol."
  version: 1.5.0
  title: "GAEN Verification Server API"
  contact:
    email: "yonatan.meschede-krasa@pathcheck.org"
  license:
    name: Apache 2.0
    url: "https://github.com/google/exposure-notifications-verification-server/blob/main/LICENSE"
tags:
- name: "VerifyCode"
  description: "Verify verification codes to recieve a long term token (a JWT) that can later be used to sign TEKs"
  externalDocs:
    description: "Verification Certificate HMAC Flow Overview"
    url: "https://bit.ly/314qCXv"
- name: "IssueCertificate"
  description: "Accept a long term token and an HMAC of the TEKs to generate a Verification Certificate"
  externalDocs:
    description: "Verification Certificate HMAC Flow Overview"
    url: "https://bit.ly/314qCXv"

paths:
  /verify:
    post:
      tags:
      - VerifyCode
      summary: "Verifies a GAEN Verification Code"
      operationId: VerifyCodeRequest
      description: "User submits verification code received from contact tracer for identity verification"
      externalDocs:
        description: "Reference for API implementation."
        url: "https://bit.ly/3g9JZ6l"
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: "VerifyCode Request Body"
        schema:
          $ref: '#/definitions/VerifyCodeRequest'
      - in: header
        name: X-API-KEY
        description: "Device API key"
        type: string
      responses:
        200:
          description: "Response Object with Long Term Token"
          schema:
            $ref: '#/definitions/VerifyCodeResponse'
        400:
          description: "Bad Request Error"
          schema:
            $ref: '#/definitions/VerifyCodeErrorResponse'
  /certificate:
    post:
      tags:
      - IssueCertificate
      summary: "Create Verification Certificate with Metadata"
      operationId: IssueCertificateRequest
      description: "Accept a long term token and an HMAC of the TEKs to generate a verification certificate"
      externalDocs:
        description: "Reference for API implementation."
        url: "https://bit.ly/3g9JZ6l"
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: "IssueCertificate Request Body"
        schema:
          $ref: '#/definitions/IssueCertificateRequest'
      - in: header
        name: X-API-KEY
        description: "Device API key"
        type: string
      responses:
        200:
          description: "Response Object with verification certificate"
          schema:
            $ref: '#/definitions/IssueCertificateResponse'
        400:
          description: "Bad Request Error"
          schema:
            $ref: '#/definitions/IssueCertificateErrorResponse'

definitions:
  VerifyCodeRequest:
    type: object
    required:
    - code
    properties:
      code:
        type: string
        description: "Code to be verified when reporting a COVID test"
        example: "98114473"
  VerifyCodeResponse:
    type: object
    properties: 
      testtype: 
        type: string
        description: "Possible Covid Test Results Outcome"
        example: "confirmed"
        enum:
          - "confirmed"
          - "likely"
          - "negative"
      symptomdate: 
        type: string
        description: "ISO 8601 formatted date, YYYY-MM-DD."
        example: "2020-08-14"
      token: 
        type: string
        description: "Long term token used to generate verification certificate"
        example: "eyJhkGciOiJFUvI1NiIsImtpZBI7InYxIiwidHlwIjoiSldUIn0.eyJhdWQiOiJvcmcucGF0aGNoZWNrLnZlcglmeSIsImV4cCI6MTU5Nzc2NTIzMywianRpIjoiNVoxOTlTUzRKSkxfGTxCSHpVSVBuVzR2ZVoyZ3AwVWxmRFFKSjViY09VK05KZEc4em9SSXJjY05BUWpZcFZmdk0rMzYvV1l5Sk41dUd3VGRzSXpuK1JWRXJRMk1xTncyMkNJSHRuUktSSXBKRzgzYzRoLzE5MkJzMFJvdm1WK0oiLCJpYXQiOjE1OTc2Nzg4MzMsImlzcyI6Im9yZy5wYXRoY2hlY2sudmVyaWZ5Iiwic3ViIjoiY29uZmlybWVkLjIwMjAtMDgtMTQifQ.OkdAddgvXdXJyTEffGrR5DJ326dhhdwtSZzaaCtxw5wZeR8ZCuCRm8oLKz6qVckTXwDzCSy6y3SlKA6Vboz2Fg"
  VerifyCodeErrorResponse:
    type: object
    properties:
      error:
        type: string
        example: "verification code invalid"
        description: "Error message. e.g. Not Found"
      error_code: 
        type: string
        example: "token_invalid"
        description: "Server error code."
  IssueCertificateRequest:
    type: object
    required:
    - token
    - ekeyhmac
    properties:
      token: 
        type: string
        description: "Long Term Token received from Verify Code request and required for issuing verification certificate"
        example: "eyJhkGciOiJFUvI1NiIsImtpZBI7InYxIiwidHlwIjoiSldUIn0.eyJhdWQiOiJvcmcucGF0aGNoZWNrLnZlcglmeSIsImV4cCI6MTU5Nzc2NTIzMywianRpIjoiNVoxOTlTUzRKSkxfGTxCSHpVSVBuVzR2ZVoyZ3AwVWxmRFFKSjViY09VK05KZEc4em9SSXJjY05BUWpZcFZmdk0rMzYvV1l5Sk41dUd3VGRzSXpuK1JWRXJRMk1xTncyMkNJSHRuUktSSXBKRzgzYzRoLzE5MkJzMFJvdm1WK0oiLCJpYXQiOjE1OTc2Nzg4MzMsImlzcyI6Im9yZy5wYXRoY2hlY2sudmVyaWZ5Iiwic3ViIjoiY29uZmlybWVkLjIwMjAtMDgtMTQifQ.OkdAddgvXdXJyTEffGrR5DJ326dhhdwtSZzaaCtxw5wZeR8ZCuCRm8oLKz6qVckTXwDzCSy6y3SlKA6Vboz2Fg"
      ekeyhmac: 
        type: string
        format: byte
        description: "The device generated, random key that was used to create the HMAC for the data sent to the verification server"
        example: "VVCAOU+jR87FYvKO+BqtzKuAFSAs+U9GQNZXyt++8d4="
  IssueCertificateResponse:
    type: object
    properties: 
      certificate: 
        type: string
        description: "Signed Verification Certificate"
        example: "eyJhbGviOiJFOzI1NiIsImtpZCI6InYxIiwidHlwIjoiSldUIn4.eyJhdWQiOiJvcbcucGF0aGNoZWNrLnNlcnZlciIsImV4cCI6VTU5NzY4NjcxOFbiaWF0IjvxNBk3Njg1ODE5LCJdc3FiOiJvcmcucGF0aGBoZWNrLnZlcmlmeSIsIm5iZfI6MTU7NzY4NTgxOCwigmVwb3J0VHlwZSI6ImKvbmZpcm1lZCIsInN5bXB0b21PbnNldEludGVydmFsIjoyNjYyMjcyLCJ0ZWthYWMiOiJYVkNBT1Urcko4N1BZdktPK0JxdHpLdUFPU0FzK1U5R1FNWlh5dCsrOGc0PSJ9.H1EGozRf21yGflqIIDcZO4-v15kmPMRSV8mNLQuFUvMytc_UIGu5cep1u7sANb45dJ96leQf5MjUSW1955Ol-w"
  IssueCertificateErrorResponse:
    type: object
    properties:
      error:
        type: string
        example: "verification code invalid"
        description: "Error message. e.g. Not Found"
      error_code: 
        type: string
        example: "token_invalid"
        description: "Server error code."

host: "api.gaen.extremesolution.com"
basePath: /api
schemes:
 - https