Authentication
Whether you use one of our UIKits or decide to build your own when integrating Weavy, all communication between your app and Weavy is performed through the Web API and needs to be properly authenticated.
Authentication is done with Bearer authentication over HTTPS (SSL), and this article explains how to acquire tokens for different scenarios such as server-to-server and user-to-server, and finally, it also documents some best practices when using tokens.
API keys
Tokens used for server-to-server communication are called API keys and can be generated from the environment page on your Weavy account.
An API key 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.
While API keys can be configured to never expire, we strongly recommend that you set an expiration date to prevent potential security issues.
Access tokens
When 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.
Example: Get user information for the authenticated user.
curl https://{WEAVY-SERVER}/api/user
-H "Authorization: Bearer {ACCESS-TOKEN}"
To obtain an access token you make a server-to-server request from your server to the tokens endpoint in your Weavy environment
(by default access tokens expire after 3600 seconds, but you can specify a custom lifetime with the expires_in parameter when issuing the token).
Example: Issue an access token for user with uid u256.
curl https://{WEAVY-SERVER}/api/users/u256/tokens
-X POST
-H "Authorization: Bearer {API-KEY}"
Single-Sign-On (SSO)
All our UIKits have built-in functionality for SSO and seamless authentication between your app and Weavy. The basic workflow is as follows:
- Whenever the UIKit needs to perform an API request to the Weavy environment it will ask your server to supply an access token for the authenticated user.
- Your application can then perform a server-to-server request to the tokens endpoint and return the access token (to improve response times and reduce unnecessary roundtrips, it is a good practice to store and reuse tokens until they expire).
For more details see UIKit Web authentication, UIKit React authentication and UIKit JS authentication.
Best practices
And finally, 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.