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.verify.projectaurora.cloud"
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/VerifyCodeResponse'
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: "eyJhbGciOiJFUzI1NiIsImtpZCI6InYxIiwidHlwIjoiSldUIn0.eyJhdWQiOiJvcmcucGF0aGNoZWNrLnZlcmlmeSIsImV4cCI6MTU5Nzc2NTIzMywianRpIjoiNVoxOTlTUzRKSkxfGTxCSHpVSVBuVzR2ZVoyZ3AwVWxmRFFKSjViY09VK05KZEc4em9SSXJjY05BUWpZcFZmdk0rMzYvV1l5Sk41dUd3VGRzSXpuK1JWRXJRMk1xTncyMkNJSHRuUktSSXBKRzgzYzRoLzE5MkJzMFJvdm1WK0oiLCJpYXQiOjE1OTc2Nzg4MzMsImlzcyI6Im9yZy5wYXRoY2hlY2sudmVyaWZ5Iiwic3ViIjoiY29uZmlybWVkLjIwMjAtMDgtMTQifQ.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: "eyJhbGciOiJFUzI1NiIsImtpZCI6InYxIiwidHlwIjoiSldUIn0.eyJhdWQiOiJvcmcucGF0aGNoZWNrLnZlcmlmeSIsImV4cCI6MTU5Nzc2NTIzMywianRpIjoiNVoxOTlTUzRKSkxfGTxCSHpVSVBuVzR2ZVoyZ3AwVWxmRFFKSjViY09VK05KZEc4em9SSXJjY05BUWpZcFZmdk0rMzYvV1l5Sk41dUd3VGRzSXpuK1JWRXJRMk1xTncyMkNJSHRuUktSSXBKRzgzYzRoLzE5MkJzMFJvdm1WK0oiLCJpYXQiOjE1OTc2Nzg4MzMsImlzcyI6Im9yZy5wYXRoY2hlY2sudmVyaWZ5Iiwic3ViIjoiY29uZmlybWVkLjIwMjAtMDgtMTQifQ.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: "eyJhbGviOiJFOzI1NiIsImtpZCI6InYxIiwidHlwIjoiSldUIn0.eyJhdWQiOiJvcmcucGF0aGNoZWNrLnNlcnZlciIsImV4cCI6MTU5NzY4NjcxOSbiaWF0IjoxNTk3Njg1ODE5LCJpc3MiOiJvcmcucGF0aGNoZWNrLnZlcmlmeSIsIm5iZiI6MTU7NzY4NTgxOCwigmVwb3J0VHlwZSI6ImKvbmZpcm1lZCIsInN5bXB0b21PbnNldEludGVydmFsIjoyNjYyMjcyLCJ0ZWthYWMiOiJYVkNBT1Urcko4N1BZdktPK0JxdHpLdUFPU0FzK1U5R1FNWlh5dCsrOGc0PSJ9.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.verify.projectaurora.cloud"
basePath: /api
schemes:
- https