Collection of endpoints related to Credentials
openapi: 3.0.0
info:
title: Privado ID - Issuer Agent Credentials API
description: "The Issuer Node Core API is ideal for users who need multiple identities and for integrator profiles, who want to \ncreate solutions based on Privado ID functionalities and might be interested in having access to low level \ninformation such as Merkle Trees.\nThe Issuer Node API provide the following functionalities:\n* Create and retrieve Identities\n* Create a Verifiable Credential (VC)\n* Retrieve a Verifiable Credential or a list of Verifiable Credentials\n* Generate JSON to create a QR Code and use that to accept credentials in a wallet\n* Revoke a Verifiable Credential\n* Check revocation status of a Verifiable Credential\n* Retrieve the Revocation Status of a Verifiable Credential\n* Call Agent Endpoint using the Wallet App\n* Handle connections.\n"
version: '1'
tags:
- name: Credentials
description: Collection of endpoints related to Credentials
paths:
/v2/identities/{identifier}/credentials:
post:
summary: Create Credential
operationId: CreateCredential
description: Creates a credential for the provided identity.
tags:
- Credentials
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCredentialRequest'
responses:
'201':
description: Credential Created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCredentialResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'422':
$ref: '#/components/responses/422'
'500':
$ref: '#/components/responses/500'
get:
summary: Get Credentials
operationId: GetCredentials
description: 'Returns a list of credentials for the provided identity. Results are paginated.
Filter between all | revoked | expired credentials and also perform a full text search with the query parameter.
'
tags:
- Credentials
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
- in: query
name: page
schema:
type: integer
format: uint
minimum: 1
example: 1
description: Page to fetch. First is one. If omitted, all results will be returned.
- in: query
name: credentialSubject
schema:
type: string
example: did:polygonid:polygon:amoy:2qFpPHotk6oyaX1fcrpQFT4BMnmg8YszUwxYtaoGoe
- in: query
name: schemaType
schema:
type: string
example: UniquenessCredential
description: Filter credentials by schema type (partial match)
- in: query
name: schemaUrl
schema:
type: string
example: ipfs://QmYpsAHYPrNNaNc2o9SAMrPknSAYYAbse4hYxQgMP64Tvj
description: Filter credentials by schema URL (begins with match)
- in: query
name: status
schema:
type: string
enum:
- all
- revoked
- expired
description: "Credential status:\n * `all` - All Credentials. (default value)\n * `revoked` - Only revoked credentials\n * `expired` - Only expired credentials\n"
- in: query
name: query
schema:
type: string
description: Query string to do full text search
- in: query
name: max_results
schema:
type: integer
format: uint
example: 50
default: 50
description: Number of items to fetch on each page. Minimum is 10. Default is 50. No maximum by the moment.
- in: query
name: sort
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- schemaType
- -schemaType
- createdAt
- -createdAt
- expiresAt
- -expiresAt
- revoked
- -revoked
default: -createdAt
description: 'The minus sign (-) before createdAt means descending order.
'
responses:
'200':
description: List of credentials
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialsPaginated'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/credentials/{id}:
get:
summary: Get Credential
operationId: GetCredential
description: Get a specific credential for the provided identity.
tags:
- Credentials
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
- $ref: '#/components/parameters/pathClaim'
responses:
'200':
description: Credential found
content:
application/json:
schema:
$ref: '#/components/schemas/Credential'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
delete:
summary: Delete Credential
operationId: DeleteCredential
description: Remove a specific credential for the provided identity.
tags:
- Credentials
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
- $ref: '#/components/parameters/pathClaim'
responses:
'200':
description: Credential deleted
content:
application/json:
schema:
$ref: '#/components/schemas/GenericMessage'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/credentials/revoke/{nonce}:
post:
summary: Revoke Credential
operationId: RevokeCredential
description: Revokes a specific credential for the provided identity.
tags:
- Credentials
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
- $ref: '#/components/parameters/pathNonce'
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeClaimResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
/v1/{identifier}/claims/revocation/status/{nonce}:
get:
summary: Get Revocation Status V1
operationId: GetRevocationStatus
deprecated: true
description: Endpoint to get the revocation status
tags:
- Credentials
parameters:
- $ref: '#/components/parameters/pathIdentifier'
- $ref: '#/components/parameters/pathNonce'
responses:
'200':
description: Proof
content:
application/json:
schema:
$ref: '#/components/schemas/RevocationStatusResponse'
'400':
$ref: '#/components/responses/400'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/credentials/revocation/status/{nonce}:
get:
summary: Get Revocation Status
operationId: GetRevocationStatusV2
description: Endpoint to get the revocation status
tags:
- Credentials
parameters:
- $ref: '#/components/parameters/pathIdentifier'
- $ref: '#/components/parameters/pathNonce'
responses:
'200':
description: Proof
content:
application/json:
schema:
$ref: '#/components/schemas/RevocationStatusResponse'
'400':
$ref: '#/components/responses/400'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/credentials/{id}/offer:
get:
summary: Get Credentials Offer
operationId: GetCredentialOffer
description: Returns a universal/deep link to an offer or raw offer message that can be used for accepting a claim. | Response can be in 3 formats `universalLink`, `deepLink` or `raw`. Default is `universalLink`. Raw is the raw QR code and link is a QR code with a link to the raw content. Regardless of the type, the field will always be called universalLink.
tags:
- Credentials
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
- $ref: '#/components/parameters/pathClaim'
- name: type
in: query
required: false
schema:
type: string
enum:
- universalLink
- deepLink
- raw
description: "Type:\n * `universalLink` - (default value) Returns a universal link. The preferred and more standard way to access the offer message \n * `deepLink` - Returns a deeplink with a link redirection to the original message. \n * `raw` - Returns the raw offer message.\n"
responses:
'200':
description: ok
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialOfferResponse'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'500':
$ref: '#/components/responses/500'
components:
parameters:
pathNonce:
name: nonce
in: path
required: true
description: Claim nonce
schema:
type: integer
format: int64
pathIdentifier:
name: identifier
in: path
required: true
description: Issuer identifier
schema:
type: string
pathClaim:
name: id
in: path
required: true
description: Claim identifier
schema:
type: string
schemas:
RevokeClaimResponse:
type: object
required:
- message
properties:
message:
type: string
x-omitempty: false
example: pending
CredentialsPaginated:
type: object
required:
- items
- meta
properties:
items:
type: array
items:
$ref: '#/components/schemas/Credential'
meta:
$ref: '#/components/schemas/PaginatedMetadata'
GenericMessage:
type: object
required:
- message
properties:
message:
type: string
DisplayMethod:
type: object
required:
- id
- type
properties:
id:
type: string
x-omitempty: false
type:
type: string
x-omitempty: false
enum:
- Iden3BasicDisplayMethodV1
CreateCredentialRequest:
type: object
required:
- credentialSchema
- type
- credentialSubject
properties:
credentialSchema:
type: string
x-omitempty: false
claimID:
type: string
x-go-type: uuid.UUID
x-omitempty: false
type:
type: string
x-omitempty: false
credentialSubject:
type: object
x-omitempty: false
expiration:
type: integer
format: int64
version:
type: integer
format: uint32
revNonce:
type: integer
format: uint64
subjectPosition:
type: string
merklizedRootPosition:
type: string
refreshService:
$ref: '#/components/schemas/RefreshService'
displayMethod:
$ref: '#/components/schemas/DisplayMethod'
proofs:
type: array
items:
type: string
x-omitempty: false
example: BJJSignature2021
enum:
- BJJSignature2021
- Iden3SparseMerkleTreeProof
credentialStatusType:
type: string
x-omitempty: true
example: Iden3ReverseSparseMerkleTreeProof
enum:
- Iden3commRevocationStatusV1.0
- Iden3ReverseSparseMerkleTreeProof
- Iden3OnchainSparseMerkleTreeProof2023
encryptionKey:
type: object
x-omitempty: true
example:
EncryptionKey:
summary: Encryption Key
value:
alg: ECDH-ES+A256KW
crv: P-256
kid: tu-kid
kty: EC
use: enc
x: 8UfTxPvmMFAPuqwtxaRWrWmihC_7uYF2rEnxa4lLQ_s
y: M4PFcNXKyyRJ3zNPg19FlB6O0Tlbqs8euRcflpbDtcE
example:
credentialSchema: https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json/KYCAgeCredential-v3.json
type: KYCAgeCredential
credentialSubject:
id: fill with did
birthday: 19960424
documentType: 2
expiration: 1903357766
CreateCredentialResponse:
type: object
required:
- id
properties:
id:
type: string
x-omitempty: false
EncryptedVC:
type: object
required:
- id
- data
- proof
- context
- type
- issuanceDate
- credentialStatus
properties:
id:
type: string
x-omitempty: false
data:
type: object
x-go-type: protocol.JWEJSONEncryption
x-go-type-import:
name: protocol
path: github.com/iden3/iden3comm/v2/protocol
proof:
type: object
x-go-type: verifiable.CredentialProofs
x-go-type-import:
name: verifiable
path: github.com/iden3/go-schema-processor/v2/verifiable
context:
type: string
example: https://www.w3.org/2018/credentials/examples/v1
type:
type: string
example: KYCAgeCredential
expirationDate:
$ref: '#/components/schemas/TimeUTC'
issuanceDate:
$ref: '#/components/schemas/TimeUTC'
credentialStatus:
type: object
x-go-type: verifiable.CredentialStatus
x-go-type-import:
name: verifiable
path: github.com/iden3/go-schema-processor/v2/verifiable
RevocationStatusResponse:
type: object
required:
- issuer
- mtp
properties:
issuer:
type: object
properties:
state:
type: string
rootOfRoots:
type: string
claimsTreeRoot:
type: string
revocationTreeRoot:
type: string
mtp:
type: object
required:
- existence
properties:
existence:
type: boolean
siblings:
type: array
x-omitempty: false
items:
type: string
node_aux:
type: object
properties:
key:
type: string
value:
type: string
GenericErrorMessage:
type: object
required:
- message
properties:
message:
type: string
example: Something happen
PaginatedMetadata:
type: object
required:
- total
- page
- max_results
properties:
total:
type: integer
format: uint
example: 1
page:
type: integer
format: uint
example: 1
max_results:
type: integer
format: uint
example: 50
RefreshService:
type: object
required:
- id
- type
properties:
id:
type: string
x-omitempty: false
type:
type: string
x-omitempty: false
enum:
- Iden3RefreshService2023
TimeUTC:
type: string
x-go-type: timeapi.Time
x-go-type-import:
name: timeapi
path: github.com/polygonid/sh-id-platform/internal/timeapi
example: '2023-10-26T10:59:08Z'
x-omitempty: false
CredentialOfferResponse:
type: object
required:
- universalLink
- schemaType
properties:
universalLink:
type: string
example: https://wallet.privado.id#request_uri=https%3A%2F%2Fissuer-demo.polygonid.me%2Fapi%2Fqr-store%3Fid%3Df780a169-8959-4380-9461-f7200e2ed3f4
schemaType:
type: string
example: vaccinationCertificate
Credential:
type: object
required:
- id
- proofTypes
- revoked
- schemaHash
properties:
id:
type: string
x-omitempty: false
proofTypes:
type: array
items:
type: string
example:
- BJJSignature2021
revoked:
type: boolean
example: false
schemaHash:
type: string
example: c9b2370371b7fa8b3dab2a5ba81b6838
vc:
type: object
x-go-type: verifiable.W3CCredential
x-go-type-import:
name: verifiable
path: github.com/iden3/go-schema-processor/v2/verifiable
encryptedVC:
$ref: '#/components/schemas/EncryptedVC'
responses:
'422':
description: Unprocessable Content
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'500':
description: Internal Server error
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
securitySchemes:
basicAuth:
type: http
scheme: basic