Ticket

Authen exposes APIs to create, use and delete tickets. A ticket is a opaque identifier that is associated with data. Tickets generally have a maximum number of use (often 1) and an expiration - though they can also be configured for unlimited use and with no expiration.

A common use-case for tickets is to transfer data from one system to another. This can be used, for example, as a form of single sign-on. A logged in client makes a transfer request to System A. System A generates and returns a ticket to the client. This ticket is only valid for 30 seconds and only for a single use; it's associated with the user_id. The client then sends the ticket to System B. As long as System B trusts System A, it can be sure that the owner of the ticket is the user_id associated with the ticket.

Tickets have advantages and disadvantages over alternative approaches, such as transferring encrypted and/or signed data via the client. The main advantage is that revocation and usage limits are first class features.

Create

Tickets can be created with a usage limit, an time-to-live and/or a payload:

POST /v1/totps

Parameters
Response
Sample Request
Sample Response
Errors

name	type	desc
`ttl`	int [0..]	The time to live, in seconds, of the ticket. If not specified, this default sot `60` (60 seconds). A value of `0` indicates that the ticket can be used forever.
`uses`	int [0..]	The maximum number of times the ticket can be used. If not specified, this defaults to `1`. A value of `0` indicates that the ticket can be used an unlimited number of times.
`payload`	any	Arbitrary data to associate with the ticket. This data will be returned when the ticket is used. This can be omitted/null.

name	type	desc
`ticket`	string	The ticket (this is a base64 encoded opaque value, but callers should not assume anything about this value except that it's a non-empty string).

curl -X POST "http://127.0.0.1:5200/v1/tickets" \
	-H "Content-Type: application/json" \
	-d '{
	"uses": 2,
	"ttl": 50,
	"payload": {"user_id": 9001}
}'

{"ticket":"UrX/fTU0TaEEBv1ZlhpImz1c1Ts"}

code		desc
`102009`	The project has reached the maximum configured tickets.
`102010`	The `payload` is larger than the maximum configured length.

The general error section details Authen's error responses as well as detailing all errors, including global errors, such as validation and internal server errors.

Use

Uses the ticket, returning the payload and the number of uses left (if any).

POST /v1/totps/uses

Parameters
Response
Sample Request
Sample Response
Errors

name	type	req	desc
`ticket`	string	✓	The ticket to use. This from from the response from the create endpoint.

name	type	desc
`uses`	int	The number of uses left. Null for a ticket with unlimited use.
`payload`	any	The data, if any, associated with the ticket when it was created.

curl -X POST "http://127.0.0.1:5200/v1/tickets/use" \
	-H "Content-Type: application/json" \
	-d '{"ticket": "UrX/fTU0TaEEBv1ZlhpImz1c1Ts"}'

{
	"uses": 1,
	"payload": {"user_id": 9001}
}

code		desc
`102011`	The `ticket` could not be found.

The general error section details Authen's error responses as well as detailing all errors, including global errors, such as validation and internal server errors.

Delete

Deletes the ticket.

POST /v1/totps/delete

Parameters
Response
Sample Request
Sample Response
Errors

name	type	req	desc
`ticket`	string	✓	The ticket to use. This from from the response from the create endpoint.

name	type	desc
`uses`	int	The number of uses left. Null for a ticket with unlimited use.
`deletes`	int	The number of deleted tickets (currently must be either 0 or 1).

curl -X POST "http://127.0.0.1:5200/v1/tickets/delete" \
	-H "Content-Type: application/json" \
	-d '{"ticket": "UrX/fTU0TaEEBv1ZlhpImz1c1Ts"}'

{
	"uses": 1,
	"deleted": 1
}

The general error section details Authen's error responses as well as detailing all errors, including global errors, such as validation and internal server errors.

Overview

APIS

Ticket

Create

Use

Delete