# 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."}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.empe.io/develop/issuer/api-reference/authorization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.