# Authorization

Create a new authorization request\
\
This endpoint creates a new authorization request record that will be used\
later in the token exchange process
-----------------------------------

> Creates a new authorization request

```json
{"openapi":"3.0.0","info":{"title":"issuer-service","version":"1.0.0-rc2"},"servers":[{"url":"/"}],"security":[],"paths":{"/api/v1/authorizations":{"post":{"operationId":"CreateAuthorizationRequest","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizationRequestResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"description":"Creates a new authorization request","summary":"Create a new authorization request\n\nThis endpoint creates a new authorization request record that will be used\nlater in the token exchange process","tags":["Authorization"],"parameters":[],"requestBody":{"description":"Request with presentation definition and security parameters","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuthorizationRequestDto","description":"Request with presentation definition and security parameters"}}}}}}},"components":{"schemas":{"AuthorizationRequestResponseDto":{"description":"Response DTO for a new authorization request","properties":{"id":{"type":"string","description":"The unique identifier of the authorization request","format":"uuid"},"presentation_definition":{"$ref":"#/components/schemas/PresentationDefinition","description":"The presentation definition that defines what credentials are required"},"state":{"type":"string","description":"Random string to prevent CSRF attacks","minLength":32,"maxLength":64},"nonce":{"type":"string","description":"Random string to ensure request uniqueness","minLength":32,"maxLength":64},"expires_at":{"type":"string","format":"date-time","description":"When the authorization request expires"},"code":{"type":"string","nullable":true,"description":"Code for authorization (may be null)"},"holder_did":{"type":"string","nullable":true,"description":"Holder DID (may be null)","pattern":"^did:[a-zA-Z0-9]+:[a-zA-Z0-9:.%-]+$"},"used":{"type":"boolean","description":"Whether the authorization request has been used"}},"required":["id","presentation_definition","state","nonce","expires_at"],"type":"object","additionalProperties":false},"PresentationDefinition":{"properties":{"input_descriptors":{"items":{"$ref":"#/components/schemas/InputDescriptor"},"type":"array","description":"List of input descriptors defining required credentials"},"id":{"type":"string","description":"Unique identifier for this presentation definition"}},"required":["input_descriptors","id"],"type":"object","description":"Defines requirements for a verifiable presentation.\nUsed by verifiers to specify what credentials they require."},"InputDescriptor":{"properties":{"constraints":{"properties":{"fields":{"items":{"$ref":"#/components/schemas/InputDescriptorField"},"type":"array","description":"Fields that must be present in the credential"},"limit_disclosure":{"type":"string","enum":["required"],"nullable":false,"description":"Defines disclosure requirements for credential fields"}},"required":["fields","limit_disclosure"],"type":"object","description":"Constraints that credentials must satisfy"},"id":{"type":"string","description":"Unique identifier for this input descriptor"}},"required":["constraints","id"],"type":"object","description":"Describes requirements for a credential in a presentation.\nUsed to define constraints on what credentials are acceptable\nfor a given verification purpose."},"InputDescriptorField":{"properties":{"filter":{"$ref":"#/components/schemas/JSONSchema7","description":"Optional JSON Schema that values must conform to"},"path":{"items":{"type":"string"},"type":"array","description":"Array of JSONPath expressions to locate values in the credential"}},"required":["path"],"type":"object","description":"Describes a field within an input descriptor.\nUsed to specify which paths to extract from a credential\nand optional JSON Schema filter to validate the values."},"JSONSchema7":{"properties":{"$id":{"type":"string"},"$ref":{"type":"string"},"$schema":{"$ref":"#/components/schemas/JSONSchema7Version"},"$comment":{"type":"string"},"$defs":{"properties":{},"additionalProperties":{"$ref":"#/components/schemas/JSONSchema7Definition"},"type":"object"},"type":{"anyOf":[{"$ref":"#/components/schemas/JSONSchema7TypeName"},{"items":{"$ref":"#/components/schemas/JSONSchema7TypeName"},"type":"array"}]},"enum":{"items":{"$ref":"#/components/schemas/JSONSchema7Type"},"type":"array"},"const":{"$ref":"#/components/schemas/JSONSchema7Type"},"multipleOf":{"type":"number","format":"double"},"maximum":{"type":"number","format":"double"},"exclusiveMaximum":{"type":"number","format":"double"},"minimum":{"type":"number","format":"double"},"exclusiveMinimum":{"type":"number","format":"double"},"maxLength":{"type":"number","format":"double"},"minLength":{"type":"number","format":"double"},"pattern":{"type":"string"},"items":{"anyOf":[{"$ref":"#/components/schemas/JSONSchema7Definition"},{"items":{"$ref":"#/components/schemas/JSONSchema7Definition"},"type":"array"}]},"additionalItems":{"$ref":"#/components/schemas/JSONSchema7Definition"},"maxItems":{"type":"number","format":"double"},"minItems":{"type":"number","format":"double"},"uniqueItems":{"type":"boolean"},"contains":{"$ref":"#/components/schemas/JSONSchema7Definition"},"maxProperties":{"type":"number","format":"double"},"minProperties":{"type":"number","format":"double"},"required":{"items":{"type":"string"},"type":"array"},"properties":{"properties":{},"additionalProperties":{"$ref":"#/components/schemas/JSONSchema7Definition"},"type":"object"},"patternProperties":{"properties":{},"additionalProperties":{"$ref":"#/components/schemas/JSONSchema7Definition"},"type":"object"},"additionalProperties":{"$ref":"#/components/schemas/JSONSchema7Definition"},"dependencies":{"properties":{},"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/JSONSchema7Definition"},{"items":{"type":"string"},"type":"array"}]},"type":"object"},"propertyNames":{"$ref":"#/components/schemas/JSONSchema7Definition"},"if":{"$ref":"#/components/schemas/JSONSchema7Definition"},"then":{"$ref":"#/components/schemas/JSONSchema7Definition"},"else":{"$ref":"#/components/schemas/JSONSchema7Definition"},"allOf":{"items":{"$ref":"#/components/schemas/JSONSchema7Definition"},"type":"array"},"anyOf":{"items":{"$ref":"#/components/schemas/JSONSchema7Definition"},"type":"array"},"oneOf":{"items":{"$ref":"#/components/schemas/JSONSchema7Definition"},"type":"array"},"not":{"$ref":"#/components/schemas/JSONSchema7Definition"},"format":{"type":"string"},"contentMediaType":{"type":"string"},"contentEncoding":{"type":"string"},"definitions":{"properties":{},"additionalProperties":{"$ref":"#/components/schemas/JSONSchema7Definition"},"type":"object"},"title":{"type":"string"},"description":{"type":"string"},"default":{"$ref":"#/components/schemas/JSONSchema7Type"},"readOnly":{"type":"boolean"},"writeOnly":{"type":"boolean"}},"type":"object","additionalProperties":false},"JSONSchema7Version":{"type":"string","description":"Meta schema\n\nRecommended values:\n- 'http://json-schema.org/schema#'\n- 'http://json-schema.org/hyper-schema#'\n- 'http://json-schema.org/draft-07/schema#'\n- 'http://json-schema.org/draft-07/hyper-schema#'"},"JSONSchema7Definition":{"anyOf":[{"$ref":"#/components/schemas/JSONSchema7"},{"type":"boolean"}],"description":"JSON Schema v7"},"JSONSchema7TypeName":{"type":"string","enum":["string","number","integer","boolean","object","array","null"],"description":"Primitive type"},"JSONSchema7Type":{"anyOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"},{"$ref":"#/components/schemas/JSONSchema7Object"},{"$ref":"#/components/schemas/JSONSchema7Array"}],"nullable":true,"description":"Primitive type"},"JSONSchema7Object":{"properties":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/JSONSchema7Type"}},"JSONSchema7Array":{"properties":{},"type":"object","additionalProperties":false},"ErrorResponseDto":{"description":"Extended error response with HTTP details","properties":{"name":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"code":{"type":"number","format":"double","description":"Error code"},"statusCode":{"type":"number","format":"double","description":"HTTP status code"},"httpCode":{"type":"number","format":"double","description":"HTTP code"},"method":{"type":"string","description":"HTTP method"},"path":{"type":"string","description":"Request path"},"stack":{"type":"string","description":"Stack trace (tylko w środowisku deweloperskim)"}},"required":["name","message","code","statusCode","httpCode","method","path"],"type":"object","additionalProperties":false},"CreateAuthorizationRequestDto":{"description":"Request DTO for creating a new authorization request","properties":{"presentation_definition":{"$ref":"#/components/schemas/PresentationDefinition","description":"The presentation definition that defines what credentials are required"},"state":{"type":"string","description":"Random string to prevent CSRF attacks"},"nonce":{"type":"string","description":"Random string to ensure request uniqueness"}},"required":["presentation_definition","state","nonce"],"type":"object","additionalProperties":false}}}}
```

Validate an authorization request with VP\
\
This endpoint is called by the client (wallet) to validate the authorization request.\
It validates the required parameters and the Verifiable Presentation against\
the associated presentation definition.
---------------------------------------

> Validates an authorization request with a verifiable presentation

```json
{"openapi":"3.0.0","info":{"title":"issuer-service","version":"1.0.0-rc2"},"servers":[{"url":"/"}],"security":[],"paths":{"/api/v1/authorizations/{id}/validate":{"post":{"operationId":"ValidateAuthorizationRequest","responses":{"200":{"description":"Validated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateAuthorizationResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"description":"Validates an authorization request with a verifiable presentation","summary":"Validate an authorization request with VP\n\nThis endpoint is called by the client (wallet) to validate the authorization request.\nIt validates the required parameters and the Verifiable Presentation against\nthe associated presentation definition.","tags":["Authorization"],"parameters":[{"description":"The unique identifier of the authorization request","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Request with the VP, presentation submission, and security parameters","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateAuthorizationRequestDto","description":"Request with the VP, presentation submission, and security parameters"}}}}}}},"components":{"schemas":{"ValidateAuthorizationResponseDto":{"description":"Response DTO for a validated authorization request","properties":{"code":{"type":"string","description":"The authorization code that can be exchanged for a token","minLength":1}},"required":["code"],"type":"object","additionalProperties":false},"ErrorResponseDto":{"description":"Extended error response with HTTP details","properties":{"name":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"code":{"type":"number","format":"double","description":"Error code"},"statusCode":{"type":"number","format":"double","description":"HTTP status code"},"httpCode":{"type":"number","format":"double","description":"HTTP code"},"method":{"type":"string","description":"HTTP method"},"path":{"type":"string","description":"Request path"},"stack":{"type":"string","description":"Stack trace (tylko w środowisku deweloperskim)"}},"required":["name","message","code","statusCode","httpCode","method","path"],"type":"object","additionalProperties":false},"ValidateAuthorizationRequestDto":{"description":"Request DTO for validating an authorization request","properties":{"presentation_submission":{"$ref":"#/components/schemas/PresentationSubmission","description":"The presentation submission that maps credentials to the presentation definition"},"vp_token":{"$ref":"#/components/schemas/VP","description":"The verifiable presentation containing credentials"}},"required":["presentation_submission","vp_token"],"type":"object","additionalProperties":false},"PresentationSubmission":{"properties":{"descriptor_map":{"items":{"$ref":"#/components/schemas/DescriptorMap"},"type":"array","description":"Maps between input descriptors and credentials in the presentation"},"definition_id":{"type":"string","description":"ID of the presentation definition this submission satisfies"},"id":{"type":"string","description":"Unique identifier for this submission"}},"required":["descriptor_map","definition_id","id"],"type":"object","description":"Describes how a presentation satisfies a presentation definition.\nMaps between the input descriptors in a definition and the\ncorresponding credentials in a presentation."},"DescriptorMap":{"properties":{"path_nested":{"properties":{"format":{"type":"string","description":"Format of the nested content"},"path":{"type":"string","description":"JSONPath to nested content"}},"required":["format","path"],"type":"object","description":"Optional nested path information"},"format":{"type":"string","description":"Optional format of the credential"},"path":{"type":"string","description":"JSONPath to the location of the corresponding credential in the presentation"},"id":{"type":"string","description":"ID of the input descriptor this map corresponds to"}},"required":["path","id"],"type":"object","description":"Maps between input descriptors and the corresponding credentials\nin a verifiable presentation."},"VP":{"properties":{"proof":{"$ref":"#/components/schemas/Proof","description":"Optional cryptographic proof"},"holder":{"anyOf":[{"type":"string"},{"properties":{"id":{"type":"string"}},"required":["id"],"type":"object"}],"description":"The entity that holds the presentation"},"id":{"type":"string","description":"Optional unique identifier for the presentation"},"verifiableCredential":{"items":{"$ref":"#/components/schemas/VC"},"type":"array","description":"Array of verifiable credentials included in the presentation"},"type":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"description":"Type of the verifiable presentation"},"@context":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"description":"JSON-LD context"}},"required":["holder","verifiableCredential","type","@context"],"type":"object","description":"Represents a Verifiable Presentation that contains verifiable credentials.\n\nA Verifiable Presentation (VP) is a data model that packages Verifiable Credentials\nfor sharing with a verifier. It includes cryptographic proof of the holder's control\nover the presented credentials.\n\nThe model follows the W3C Verifiable Presentations Data Model specification and can be\nserialized as JSON-LD."},"Proof":{"properties":{"challange":{"type":"string"},"nonce":{"type":"string"},"jws":{"$ref":"#/components/schemas/Base64"},"proofValue":{"$ref":"#/components/schemas/Base64"},"proofPurpose":{"$ref":"#/components/schemas/ProofPurpose"},"verificationMethod":{"$ref":"#/components/schemas/DIDUri"},"created":{"type":"string"},"type":{"$ref":"#/components/schemas/ProofType"}},"required":["proofPurpose","verificationMethod","created","type"],"type":"object"},"Base64":{"type":"string"},"ProofPurpose":{"type":"string","enum":["assertionMethod","authentication","keyAgreement","contractAgreement","capabilityInvocation","capabilityDelegation"]},"DIDUri":{"type":"string"},"ProofType":{"type":"string","enum":["EcdsaSecp256k1Signature2019","EcdsaSecp256r1Signature2019","SchnorrSecp256k1Signature2019","Ed25519Signature2018","Ed25519Signature2020","JwtProof2020","JsonWebSignature2020"],"nullable":false},"VC":{"$ref":"#/components/schemas/VCv1_1","description":"Current version of the Verifiable Credential format used in the implementation"},"VCv1_1":{"properties":{"evidence":{"additionalProperties":false,"type":"object","description":"Additional supporting information for the claims in the credential"},"credentialStatus":{"items":{"$ref":"#/components/schemas/CredentialStatus"},"type":"array","description":"Credential status information, such as revocation or suspension"},"credentialSchema":{"$ref":"#/components/schemas/CredentialSchema","description":"Schema that defines the structure of the credential subject"},"expirationDate":{"type":"string","description":"Date and time when the credential expires"},"proof":{"$ref":"#/components/schemas/Proof","description":"Cryptographic proof that can be used to detect tampering and verify the issuer"},"credentialSubject":{"anyOf":[{"$ref":"#/components/schemas/CredentialSubject"},{"items":{"$ref":"#/components/schemas/CredentialSubject"},"type":"array"}],"description":"Claims about the subject of the credential"},"issuanceDate":{"type":"string","description":"Date and time when the credential was issued"},"issuer":{"$ref":"#/components/schemas/Issuer","description":"Entity that issued the credential"},"id":{"$ref":"#/components/schemas/URI","description":"Unique identifier for the credential"},"type":{"items":{"type":"string"},"type":"array","description":"Credential type information that defines what the credential represents"},"@context":{"anyOf":[{"items":{"$ref":"#/components/schemas/URI"},"type":"array"},{"$ref":"#/components/schemas/URI"}],"description":"JSON-LD context that defines the vocabulary of the credential"}},"required":["credentialSubject","issuanceDate","issuer","type","@context"],"type":"object","description":"Verifiable Credential format following W3C VC Data Model 1.1 specification."},"CredentialStatus":{"description":"A single entry in a bitstring-based status list, per VC-DATA-MODEL-2.0","properties":{"id":{"$ref":"#/components/schemas/URI"},"type":{"type":"string","enum":["BitstringStatusListEntry"],"nullable":false},"statusPurpose":{"anyOf":[{"$ref":"#/components/schemas/StatusPurpose"},{"type":"string"}]},"statusListIndex":{"type":"number","format":"double"},"statusListCredential":{"$ref":"#/components/schemas/URI"},"statusSize":{"type":"number","format":"double"},"statusMessage":{"items":{"properties":{"message":{"type":"string"},"status":{"type":"string"}},"additionalProperties":{},"required":["message","status"],"type":"object"},"type":"array"}},"required":["type","statusPurpose","statusListIndex","statusListCredential"],"type":"object","additionalProperties":false},"URI":{"type":"string"},"StatusPurpose":{"enum":["refresh","revocation","suspension","message"],"type":"string"},"CredentialSchema":{"properties":{"type":{"type":"string","enum":["JsonSchemaValidator2018"],"nullable":false,"description":"The type of schema validator, currently only supporting JsonSchemaValidator2018"},"id":{"$ref":"#/components/schemas/URI","description":"The identifier for the schema, typically a URI pointing to the schema definition"}},"required":["type","id"],"type":"object","description":"Represents a credential schema reference that defines the structure of claims in a credential.\nFollowing W3C VC Data Model, this provides the means to validate credential contents."},"CredentialSubject":{"$ref":"#/components/schemas/Record_string.unknown_"},"Record_string.unknown_":{"properties":{},"additionalProperties":{},"type":"object","description":"Construct a type with a set of properties K of type T"},"Issuer":{"properties":{"name":{"type":"string"},"id":{"$ref":"#/components/schemas/DIDUri"}},"required":["id"],"type":"object","description":"Normalized representation of an issuer after processing InputIssuer."}}}}
```