API Overview¶

Alias provides a RESTful API for interacting with users and clients. HTTPS must be used for all requests. The JSON data format is used for request and response data, where applicable.

Base URL¶

All API endpoints are located under a base URL.

https://projectalias.com/api/

For convenience, full URLs are used throughout this documentation.

Authentication¶

Endpoints usually require authentication via OAuth 2.0 access token, provided as a bearer token in the Authorization HTTP header. This access token will usually also need a particular scope (or scopes) to be used with an endpoint.

See the OAuth 2.0 section for details the available scopes, and how to request access tokens.

Authentication Example

HTTP

GET /api/oidc/userinfo HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/oidc/userinfo" \
    -H "Authorization: Bearer <access-token>"

Python

import requests
r = requests.get('https://projectalias.com/api/oidc/userinfo',
                 headers={'Authorization': 'Bearer <access-token>'})

Request Options¶

Some endpoints support URL querystring options. The following option types are used.

Option Types

Type	Description	Examples
`string`	Regular strings.	`foo`, `bar`
`integer`	Whole numbers.	`-1`, `0`, `1`
`boolean`	Boolean values.	`true`, `false`
`date-time`	RFC3339 date-time strings.	`2020-01-19T10:30:00Z`
`[<type>]`	Same as the regular type, but multiple values are supported. Separate values with `,`.	`foo,bar`

Error Responses¶

Errors are indicated with standard HTTP status codes. In some cases, details of the error are included in an application/json response body.

Field	Type	Description
`error`	`string`	An error code.
`error_description`	`string`	An optional human-readable description of the error.