Last active
January 29, 2024 23:05
-
-
Save VerifiedIncMachine/ef399f6b5ce6545eb4d7ec3e85d87dd2 to your computer and use it in GitHub Desktop.
Obtain User Credentials Open API Spec
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
openapi: 3.1.0 | |
info: | |
title: Credentials Receiving | |
description: Spec for receiving user identity data. Webhook for the push or /sharedCredentials for the pull. | |
version: 1.0.0 | |
servers: | |
- url: https://core-api.verified.inc | |
description: The URL for the /sharedCredentials path to use if doing the pull method | |
webhooks: | |
/verified/credentials: | |
post: | |
summary: Recieve credential data | |
description: > | |
Webhook for receiving shared credentials data securely stored after a user response. | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
type: | |
type: string | |
description: a full-stop delimited type associated with the event, i.e. user.credentials.push | |
timestamp: | |
type: string | |
format: date-time | |
description: Timestamp of when the event occurred. | |
data: | |
$ref: '#/components/schemas/SharedCredentials' | |
description: the actual event data associated with the event, i.e. actual user credential data | |
required: | |
- type | |
- timestamp | |
- data | |
parameters: | |
- in: header | |
name: X-Signature | |
schema: | |
type: string | |
description: > | |
The cryptographic signature of the request is generated using Verified Inc's public ECC key. The signature is created by first hashing the webhook payload using a sha256 digest. The resulting signature is used to verify the authenticity and integrity of the webhook payload. This verification can be considered supplementary if provided Verified Inc. with a shared secret to use for authentication. | |
- in: header | |
name: Authorization | |
schema: | |
type: string | |
description: > | |
A shard secret provided by your brand to Verified Inc to use for authorization. Please note that we can provide the shared secret on any header you prefer. | |
responses: | |
200: | |
description: Success credential data received | |
403: | |
description: Not authenticated | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
500: | |
description: Unexpected error | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
paths: | |
/sharedCredentials/{uuid}: | |
get: | |
summary: Retrieve shared credentials | |
description: > | |
Fetches shared credentials data securely stored after a user response. This is the pull method. | |
The UUID is obtained via the redirect url's query param, sharedCredentialsUuid. | |
parameters: | |
- in: path | |
name: uuid | |
required: true | |
schema: | |
type: string | |
format: uuid | |
description: Unique identifier of the shared credentials. | |
- in: header | |
name: Authorization | |
required: true | |
schema: | |
type: string | |
description: > | |
Your brand's API Key provided to you by Verified Inc. | |
responses: | |
200: | |
description: Success credenitals grabbed | |
403: | |
description: Not authenticated | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
500: | |
description: Unexpected error | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
components: | |
schemas: | |
VerificationMethodEnum: | |
type: string | |
enum: | |
- self_attested | |
- phone_carrier | |
- otp | |
description: Enum describing the verification method status. | |
CredentialStatusEnum: | |
type: string | |
enum: | |
- valid | |
- revoked | |
description: Enum describing the credential status. | |
CredentialData: | |
type: object | |
oneOf: | |
- $ref: '#/components/schemas/CredentialData' | |
- type: array | |
items: | |
$ref: '#/components/schemas/Credential' | |
additionalProperties: | |
type: string | |
description: Credenital data can be an key value pair object or could be an array of sub-credentials | |
BaseCredential: | |
type: object | |
properties: | |
data: | |
$ref: '#/components/schemas/CredentialData' | |
id: | |
type: string | |
format: uuid | |
type: | |
type: string | |
expirationDate: | |
type: integer | |
format: int64 | |
description: Issuance date represented as milliseconds since the Unix epoch. | |
required: | |
- type | |
- data | |
Credential: | |
allOf: | |
- $ref: '#/components/schemas/BaseCredential' | |
- type: object | |
properties: | |
verificationMethod: | |
$ref: '#/components/schemas/VerificationMethodEnum' | |
status: | |
$ref: '#/components/schemas/CredentialStatusEnum' | |
issuerUuid: | |
type: string | |
format: uuid | |
issuanceDate: | |
type: number | |
format: int64 | |
description: Issuance date represented as milliseconds since the Unix epoch. | |
required: | |
- verificationMethod | |
- status | |
- issuerUuid | |
- issuanceDate | |
SharedCredentials: | |
type: object | |
properties: | |
credentials: | |
type: array | |
items: | |
$ref: '#/components/schemas/Credential' | |
email: | |
type: string | |
nullable: true | |
description: Required if phone is not provided | |
phone: | |
type: string | |
nullable: true | |
description: Required if email is not provided | |
uuid: | |
type: string | |
format: uuid | |
required: | |
- uuid | |
- credentials | |
Error: | |
type: object | |
required: | |
- message | |
properties: | |
message: | |
description: A human readable error message | |
type: string | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment