Authentication
Almost all endpoints on your AirServer Connect will require authentication before a request is processed.
Access control is role-based, with two defined roles (admin and moderator) and each role has
separate read and write permissions. The read permission (r) is required for endpoints/methods which serve out
information but do not modify device state. The write permission (w) is required for endpoints/methods
which modify device state.
The admin role is allowed to access/modify device state, and the moderator role is allowed to
moderate incoming and active screen mirroring sessions.
Methods
You have two choices of presenting your authentication key, header-based and as a query parameter. Both are equivalent, so you may choose whichever method you prefer.
1. Authorization Header
You can present the authorization token as a request header, using the standard Authorization
header field. The API will accept either Bearer or Basic as the scheme.
For example, if your API key is 102a0855-8fa6-4731-89b6-a45a1658b7f7 then you can use either
...
Authorization: Basic 102a0855-8fa6-4731-89b6-a45a1658b7f7
...
or
...
Authorization: Bearer 102a0855-8fa6-4731-89b6-a45a1658b7f7
...
2. Query Parameter
All of the active endpoints (such as /system and /events) accept an extra query parameter
apiKey which you may use instead of using the Authorization header.
This apiKey parameter will be expected to contain either the API key, or a valid JWT token.
Using the same example as before, your query could look like:
GET /api/v1/system?apiKey=102a0855-8fa6-4731-89b6-a45a1658b7f7
Key types
You can use either of our two key types, since they are equivalent in most use-cases.
The API Key method is the first method that was added, and it is retained for backwards compatibility. It has the benefit of being both shorter and simpler, if you do not have a need for limiting access.
JWT tokens are the only supported key type which allows you to restrict which token is capable of performing which actions. For example, you might want a token which can only observe system events without the ability to make changes to system settings.
API Key
You can authenticate using the API key from Device Management on your AirServer Connect.
The API key has the following capabilities: admin:r admin:w moderator:r moderator:w
If you want more fine-grained access control, you should use a JWT token instead.
JWT
JWT tokens are generated from your API key. They can optionally have a limited validity period, and you can control what operations each token is allowed to perform.
Bear in mind that JWT tokens are not revokable after they have been issued. Your only option is to generate a new API key, which will revoke all JWT tokens that were issued with the previous API key. This is one reason why it may be a good idea to use tokens with a validity period, since their lifetime is limited to that period. Of course, the drawback is that those tokens need to be periodically renewed. One way to solve this is to do something similar to OAuth Refresh Tokens.
We use standard JWT token claims, but we have added the roles claim to hold the granted permissions.
This claim must be an array of strings, where each string is of the form {role}:{permissions}.
The role will be either admin or moderator, and permissions will be some combination of r and/or
w. For example, admin:r grants admin read permissions to the token, but admin:rw grants both
read and write permissions for the admin role.
The JWT token must be of type HS256, and it uses your API key to derive its signing key.
To derive your JWT token signing key, you take the HMAC-SHA256 of your API key, using AirServerApiJwt
as your password.
In pseudocode:
jwt_signing_key = HMAC_SHA256("AirServerApiJwt", "{your AirServer Connect API key}")
e.g.
jwt_signing_key = HMAC_SHA256("AirServerApiJwt", "102a0855-8fa6-4731-89b6-a45a1658b7f7")
Example JWT token generator
| admin | moderator | ||
|---|---|---|---|
| read | write | read | write |