API authentication

Authenticating against the Web API is done using Bearer authentication over HTTPS (SSL). This article documents some best practices when using tokens, and explains how to acquire tokens for different scenarios such as server-to-server and user-to-server.

Best practices

Here are some basic considerations to keep in mind when using tokens:

  • Keep it secret. Keep it safe: A token should be treated like any other credential and revealed only to services that need it.
  • Give tokens an expiration: Technically, once a token is created, it is valid forever—unless it is revoked and/or configured to expire. This could pose potential issues so you should develop a strategy for expiring and/or revoking tokens.
  • Embrace HTTPS: Do not send tokens over HTTP connections as those requests can be intercepted and tokens compromised.
  • Store and reuse: Reduce unnecessary roundtrips that extend your application's attack surface, by storing and re-using tokens. Rather than always creating or requesting new tokens, use the stored tokens during future calls until they expire. How you decide to store your tokens is crucial to defending your application against malicious attacks. Typical solutions include databases and configuration files.

Server-to-server

An API key is used for server-to-server communication and can be generated from the management interface. While API keys can be configured to never expire, we strongly recommend that you set an expiration date to prevent potential security issues.

API keys does not associate your request with a user account. Instead, permissions are evaluated in the sudo context which gives your app the powers of a "super user". It is therefore very important that the you store the token securely and never expose it in client side code or similar.

User-to-server

When you your application acts on behalf of a user, it performs a user-to-server request. These requests must contain an access token for the user in the Authorization header and associates the request with the authenticated user.

To obtain an access token you make a request from your server to the Weavy backend as described below. The request should be made to the /api/users/{uid}/tokens endpoint. If a matching user is found, the Weavy backend returns an access token. If no matching user is found, the Weavy backend first creates a new user account with the specified uid and then issues an access token.

The uid is a string that uniquely identifies your user (typically your internal user id), but since it cannot contain whitespace and must contain at least one non-digit you might need to customize it. For instance, if a user has the integer id 256 in your system you can create an uid by adding a one letter prefix, e.g. "u256".

The example below shows a request that returns an access token. Since this is a server-to-server request the {token} parameter should be an API key.

$ curl -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -X POST https://{weavy-server}/api/users/{uid}/tokens

{
    "access_token": "wyu_IlLQ7qGxU6iRE5pqb6Tle2zBXq4vPu1AgrqQ",
    "expires_in": 3600
}

By default access tokens expire after 3600 seconds (1 hour) but you can optionally specify a custom lifetime with the expires_in parameter. The /api/users/{uid}/tokens endpoint can also be used to sync user profile data from your application to the Weavy backend. You typically want to set at least a name and maybe a profile picture.

Example: Request a token valid for 86400 seconds (24 hours) and set name of user to "John Doe".

$ curl -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{expires_in: 86400, name: 'John Doe'}" https://{weavy-server}/api/users/{uid}/tokens
Weavy Docs