Authorizations API

This API allows managing authorizations in the system. It provides endpoints to create, read, update, and delete authorizations, as well as to handle signatures and attachments associated with the authorizations.

The Authorization Object

The Authorization object represents an authorization in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenant": "tenant123",
  "formId": "form123",
  "key": "consent_form",
  "label": "Consent Form",
  "identityKey": "email",
  "identityValue": "user@example.com",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "expiresAt": "2028-01-01T00:00:00Z",
  "ipAddress": "192.168.1.1",
  "policyLink": "https://example.com/policy",
  "externalId": "ext123",
  "tags": ["important", "urgent"],
  "authorizedAt": "2023-01-01T12:00:00Z",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-02T12:00:00Z",
  "hasAttachments": true,
  "hasSignatures": true
}

Attributes

Attribute	Description	Type
id	Unique identifier of the authorization	String
tenant	Tenant identifier	String
formId	Associated form ID (optional)	String
key	Key identifying the type of authorization	String
label	Descriptive label of the authorization	String
identityKey	Signer's identity key	String
identityValue	Signer's identity value	String
borrowerId	Associated borrower's ID (optional)	String
expiresAt	Expiration date and time	String (ISO 8601)
ipAddress	IP address from where the authorization was created	String
policyLink	Link to the associated policy (optional)	String
externalId	External identifier (optional)	String
tags	Tags associated with the authorization	Array of String
authorizedAt	Authorization date and time	String (ISO 8601)
createdAt	Creation date and time	String (ISO 8601)
updatedAt	Last update date and time	String (ISO 8601)
hasAttachments	Indicates if the authorization has attachments	Boolean
hasSignatures	Indicates if the authorization has signatures	Boolean

Available Operations

Create a New Authorization

Creates a new authorization in the system.

POST /v1/authorizations

Input Parameters:

Parameter	Description	Type	Required
tenant	Tenant identifier	String	Yes
key	Key identifying the type of authorization	String	Yes
identityKey	Signer's identity key	String	Yes
identityValue	Signer's identity value	String	Yes
formId	Associated form ID	String	No
borrowerId	Associated borrower's ID	String	No
ipAddress	IP address from where the authorization is created	String	No
policyLink	Link to the associated policy	String	No
externalId	External identifier	String	No
tags	Tags associated with the authorization	Array of String	No

Example Request:

{
  "tenant": "tenant123",
  "key": "consent_form",
  "identityKey": "email",
  "identityValue": "user@example.com",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "policyLink": "https://example.com/policy",
  "tags": ["important", "urgent"]
}

Successful Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Retrieve an Authorization

Retrieves the information of a specific authorization.

GET /v1/authorizations/:authorization_id

Path Parameters:

Parameter	Description
authorization_id	ID of the authorization to retrieve

Successful Response:

The response will be a complete Authorization object, as described above.

Delete an Authorization

Deletes an authorization from the system.

DELETE /v1/authorizations/:authorization_id

Path Parameters:

Parameter	Description
authorization_id	ID of the authorization to delete

Successful Response:

Status code 204 (No Content) if the deletion was successful.

Sign an Authorization

Initiates the signing process of an authorization by sending an OTP.

POST /v1/authorizations/:authorization_id/signatures

Path Parameters:

Parameter	Description
authorization_id	ID of the authorization to sign

Input Parameters:

Parameter	Description	Type	Required
value	Contact value to send the OTP	String	Yes
contactMethod	Contact method (email, sms, etc.)	String	Yes
templateId	Template ID for the OTP message	String	Yes
codeSize	OTP code size	Integer	No
expiresIn	OTP expiration time in seconds	Integer	No
maxAttempts	Maximum number of allowed attempts	Integer	No

Example Request:

{
  "value": "user@example.com",
  "contactMethod": "email",
  "templateId": "otp_template_1",
  "codeSize": 6,
  "expiresIn": 300,
  "maxAttempts": 3
}

Successful Response:

{
  "otpId": "otp123456"
}

Verify Authorization Signature

Verifies the OTP code to complete the signing of an authorization.

POST /v1/authorizations/:authorization_id/signatures/attempt

Path Parameters:

Parameter	Description
authorization_id	ID of the authorization to verify

Input Parameters:

Parameter	Description	Type	Required
otpId	Previously received OTP ID	String	Yes
code	OTP code entered by the user	String	Yes

Example Request:

{
  "otpId": "otp123456",
  "code": "123456"
}

Successful Response:

Status code 202 (Accepted) if the verification was successful.

List Authorizations

Retrieves a paginated list of authorizations with filtering and sorting options.

GET /v1/authorizations

Query Parameters:

Parameter	Description	Type
borrower-id	Borrower's ID to filter	String
search	Text to search in authorizations	String
page	Page number (default: 1)	Integer
per-page	Items per page (default: 10)	Integer
key	Filter by authorization key	String
sort-by	Field to sort by	String
sort-direction	Sorting direction (asc or desc)	String

Successful Response:

The response will be a paginated list of Authorization objects.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page