User Endpoints¶

These endpoints allow interacting with a connected user. They require authentication with an active user token. They are all CORS enabled, so can be used directly from a browser.

User Info¶

GET https://projectalias.com/api/oidc/userinfo

The OpenID Connect userinfo endpoint. Returns basic user information.

Authentication

Scope	Required
`openid`	Yes
`nickname`	No

Response Body

Field	Type	Description
`sub`	`string`	The alias ID for the user.
`nickname`	`string`	The nickname the user provided. Only included if the token has the `nickname` scope.

Examples

Example Request

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>'})

Example Response

{
    "sub": "epGEcGfc6LQMmKTqffWW2g",
    "nickname": "Fred"
}

Connection¶

When a user approves a OAuth 2.0 request from a client, a connection between the user and client is established.

The connection records the user's alias ID generated for their connection with the client, the scopes they granted, any communication channels they granted, and the nickname they provided (if relevant).

The connection is updated when the user approves more permissions in subsequent auth requests, or revokes permissions from the Alias UI. A user can also revoke a connection entirely if they desire.

Details¶

GET https://projectalias.com/api/connection

Fetch details of the user's connection with the client.

Authentication

Scope	Required
`openid`	Yes
`contact`	No
`nickname`	No

Querystring Options

Option	Type	Default	Description
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`client_id`	`string`	The ID for the client.
`alias_id`	`string`	The alias ID for the user.
`scopes`	`[string]`	The scopes the user has granted the client.
`channels`	`[string]`	The communication channels the user has granted the client. `null` if the token doesn't have the `contact` scope.
`nickname`	`string`	The nickname the user provided. `null` if the token doesn't have the `nickname` scope.
`create_dt`	`date-time`	When the connection between the client and user was first created.
`update_dt`	`date-time`	When the connection between the client and user was last updated.

Examples

Example Request

HTTP

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

cURL

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

Python

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

Example Response

{
    "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
    "alias_id": "epGEcGfc6LQMmKTqffWW2g",
    "scopes": ["openid", "offline_access", "contact", "nickname"],
    "channels": ["_meta", "notifications", "product_updates"],
    "nickname": "Fred",
    "create_dt": "2020-01-19T10:30:00+00:00",
    "update_dt": "2020-06-30T12:15:30+00:00"
}

Contact User¶

POST https://projectalias.com/api/contact

Send a message to the user on a communication channel.

An outbound message is created, with one delivery record for the user. The delivery record can be checked to determine if the message has been delivered successfully.

Authentication

Scope	Required
`contact`	Yes

Request Body

Field	Type	Required	Description
`version`	`string`	Yes	The version of the message schema being used. `v0` is the only version currently supported.
`outbound_message_id`	`string`	No	The ID for this outbound message. Will be generated if not provided. 10-30 characters (inclusive). Must match `^[0-9a-zA-Z-_]+$`.
`channel`	`string`	Yes	The communication channel to send the message on. The token must include this channel.
`title`	`string`	Yes	The message title. 5-100 characters (inclusive).
`body`	`string`	No	The message body. 5-500 characters (inclusive).
`link`	`object`	No	Details of the message link.
`link.uri`	`string`	Yes	The message link URI.
`link.text`	`string`	No	Custom link text to display. 1-50 characters (inclusive).

Response Body

Field	Type	Description
`outbound_message_id`	`string`	The ID for the created outbound message.

Examples

Example Request

HTTP

POST /api/contact HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "version": "v0",
    "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
    "channel": "notifications",
    "title": "Here is your reminder",
    "body": "You asked to be reminded about this note.",
    "link": {
        "uri": "https://example.com/notes/z7I6s3jljh5RUoUYmqxxPw",
        "text": "Open your note"
    }
}

cURL

curl -XPOST "https://projectalias.com/api/contact" \
    -H "Authorization: Bearer <access-token>" \
    -H "Content-Type: application/json" \
    -d '{
            "version": "v0",
            "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
            "channel": "notifications",
            "title": "Here is your reminder",
            "body": "You asked to be reminded about this note.",
            "link": {
                "uri": "https://example.com/notes/z7I6s3jljh5RUoUYmqxxPw",
                "text": "Open your note"
            }
        }'

Python

import requests
r = requests.post('https://projectalias.com/api/contact',
                  headers={'Authorization': 'Bearer <access-token>'},
                  json={'version': 'v0',
                        'outbound_message_id': 'LzIX47-iIDVpNmnbXqCYXg',
                        'channel': 'notifications',
                        'title': 'Here is your reminder',
                        'body': 'You asked to be reminded about this note.',
                        'link': {'uri': 'https://example.com/notes/z7I6s3jljh5RUoUYmqxxPw',
                                 'text': 'Open your note'}})

Example Response

{
    "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg"
}

Message Deliveries¶

When a client tries to send a message to a user, a delivery record is created. Delivery records initially have the status of delivering. If the message is delivered successfully, the status is updated to delivered. If the message couldn't be delivered - e.g. because the user has revoked the message's channel - the status is updated to failed.

Search¶

GET https://projectalias.com/api/deliveries

List delivery records for messages that have been sent to the user by the client. A number of querystring options are provided to filter results.

Authentication

Scope	Required
`contact`	Yes

Querystring Options

Option	Type	Default	Description
`channel`	`[string]`		Filter by message channel.
`status`	`[string]`		Filter by delivery status. Statuses are `delivering`, `delivered`, `failed`.
`created_from`	`date-time`		Filter to deliveries created on/after a date-time. `T00:00:00Z` is appended if only a date is provided.
`created_to`	`date-time`		Filter to deliveries created on/before a date-time. `T23:59:59Z` is appended if only a date is provided.
`updated_from`	`date-time`		Filter to deliveries updated on/after a date-time. `T00:00:00Z` is appended if only a date is provided.
`updated_to`	`date-time`		Filter to deliveries updated on/before a date-time. `T23:59:59Z` is appended if only a date is provided.
`sort`	`[string]`	`-created,-id`	Set result sort order. Supports sorting by `id`, `created`, `updated`. Prefix `-` to sort descending.
`offset`	`integer`	`0`	The offset of the first result to return in this page of results.
`limit`	`integer`	`10`	The number of results to return in this page.
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`deliveries`	`[object]`	An array of delivery records.
`deliveries[].client_id`	`string`	The ID for the client.
`deliveries[].outbound_message_id`	`string`	The ID for the outbound message.
`deliveries[].alias_id`	`string`	The alias ID for the user.
`deliveries[].channel`	`string`	The communication channel the message was sent on.
`deliveries[].status`	`string`	One of `delivering`, `delivered`, `failed`.
`deliveries[].create_dt`	`date-time`	When the delivery record was first created.
`deliveries[].update_dt`	`date-time`	When the delivery record was last updated.
`paging`	`object`	Result paging information.
`paging.total`	`integer`	The total number of results for this search.
`paging.more`	`boolean`	Whether there are more pages of results.
`paging.next`	`integer`	The offset of the next page of results. `null` if no more pages.

Examples

Example Request

HTTP

GET /api/deliveries?channel=notifications&created_from=2020-01-19T10:30:00Z HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/deliveries?channel=notifications&created_from=2020-01-19T10:30:00Z" \
    -H "Authorization: Bearer <access-token>"

Python

import requests
r = requests.get('https://projectalias.com/api/deliveries',
                 headers={'Authorization': 'Bearer <access-token>'},
                 params={'channel': 'notifications',
                         'created_from': '2020-01-19T10:30:00Z'})

Example Response

{
    "deliveries": [
        {
            "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
            "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
            "alias_id": "epGEcGfc6LQMmKTqffWW2g",
            "channel": "notifications",
            "status": "delivered",
            "create_dt": "2020-06-30T13:30:00+00:00",
            "update_dt": "2020-06-30T13:30:10+00:00"
        }
    ],
    "paging": {
        "total": 1,
        "more": false,
        "next": null
    }
}

Details¶

GET https://projectalias.com/api/deliveries/<outbound_message_id>

Fetch the delivery record for a message that has been sent to the user by the client.

Authentication

Scope	Required
`contact`	Yes

Querystring Options

Option	Type	Default	Description
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`client_id`	`string`	The ID for the client.
`outbound_message_id`	`string`	The ID for the outbound message.
`alias_id`	`string`	The alias ID for the user.
`channel`	`string`	The communication channel the message was sent on.
`status`	`string`	One of `delivering`, `delivered`, `failed`.
`create_dt`	`date-time`	When the delivery record was first created.
`update_dt`	`date-time`	When the delivery record was last updated.

Examples

Example Request

HTTP

GET /api/deliveries/LzIX47-iIDVpNmnbXqCYXg HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/deliveries/LzIX47-iIDVpNmnbXqCYXg" \
    -H "Authorization: Bearer <access-token>"

Python

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

Example Response

{
    "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
    "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
    "alias_id": "epGEcGfc6LQMmKTqffWW2g",
    "channel": "notifications",
    "status": "delivered",
    "create_dt": "2020-06-30T13:30:00+00:00",
    "update_dt": "2020-06-30T13:30:10+00:00"
}