Working with Daily meeting tokens
Daily meeting tokens can be used to set options and permissions for users joining a Daily room. Examples of special privileges or options which could be granted by a token include:
- Allowing the token holder to join a private room
- Setting the token holder's user name
- Allowing the token holder to initiate screen sharing or recording during a call
- Instructing Daily to eject the token holder from a room after a specific length of time
In this guide, we'll go through everything you need to begin working with Daily meeting tokens. We will cover:
- The format of a meeting token and what data it contains
- How to obtain a meeting token
- How to use a meeting token in a Daily call
- How to validate a meeting token
Let's begin by going through what a Daily meeting token is and what kind of data it holds.
What is a Daily meeting token?
Daily meeting tokens are JSON Web Tokens (JWTs). JWTs are used to communicate data that can be verified with a shared secret value. The token is a string made up of three base64-encoded parts separated by periods:
- Header: contains information about algorithm and token type
- Payload: contains token claims like expiry, issue time, and room privileges
- Signature: produced by taking the header, payload, and algorithm type, and signing the whole thing with a secret
The JWT standard is detailed in RFC 7519.
An example JWT could look as follows:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE1NDg3MjE1NjksImV4cCI6MTg2NDA4MTUzOCwiciI6ImhlbGxvIiwibyI6dHJ1ZSwic3MiOnRydWUsImVyIjoibG9jYWwiLCJkIjoiMjVkZjUwNTctZWYwZC00ZDk3LWJkZTYtMGNmMjg3Mjc2Y2JiIiwiaWF0IjoxNTQ4NzIxODMxfQ.mvVciAengBR4xCblhFpo4mKYftQv1skYO4Y6IKr9Zgo
When decoding the payload (eyJuYmY...xODMxfQ), we see the following:
The above claims specify properties including:
- The token's earliest activation time (
nbf) - The token's expiry time (
exp) - The room which the token is valid for (
r) - Whether the given user can screen share (
ss) or enable recording (er) - And more...
For more details about each claim, please refer to our token property abbreviations.
A resource server can validate expiry and other relevant claims along with the token signature. If valid, the token can be used to grant access to privileged resources or operations. The primary use case of Daily's meeting token JWTs involves passing a token to Daily when joining a room. In this case, Daily itself functions as the resource server and handles token validation for you.
Getting a Daily meeting token
A Daily meeting token can be obtained either through our REST API, or by self-signing a JWT with your Daily API key.
Obtaining a token through Daily's REST API
To obtain a token through Daily's REST API, you will make a POST request to https://api.daily.co/v1/meeting-tokens. The request will contain an Authorization header with your Daily API Key. The body of the request will contain your chosen token properties. An example request could look as follows:
Obtaining a token by self-signing a JWT
A token can be self-signed either completely manually, or using your JWT library of choice. In the following JavaScript example of generating a self-signed meeting token, we'll use jsonwebtoken:
Please refer to our token property abbreviations when composing your token payload.
Security considerations and token revocation
In both token creation examples above, the token is generated for a specific room and contains an expiry time of 1 hour. We recommend narrowing the scope and lifetime of your token as much as possible. If an expiry time is not specified, the token will be active forever. If a room is not specified, the token will be valid for every room on your Daily domain. Anyone issued such a token will be able to access any room with the token's permitted privileges, indefinitely.
If a Daily-signed token is compromised, there is no way to revoke it yourself except to delete the room it was generated for (if you specified a room name for the token). If a self-signed token is compromised, it can be revoked by regenerating your Daily API key in your Daily dashboard.
Generating a token with the lowest reasonable expiry ensures that after a certain time, a compromised token becomes useless. Generating a token for a specific room if your use case allows for it further narrows its scope in case it falls into the hands of a malicious user. A malicious user with a a meeting token that does not specify expiry or a room name could join any private room on your domain at any time.
Using a Daily meeting token
Once retrieved, a meeting token should be supplied to Daily as part of the join() call object instance method parameter:
If the passed meeting token is invalid, no error will be emitted. If a user joins a call with an invalid meeting token and tries to perform a privileged operation, the operation will fail.
Validating a Daily meeting token
Daily meeting tokens can be validated by using our REST API. If you're using a self-signed token you can also validate the claims and signature in your code base without the API request. Self-validation can be performed by writing manual validation logic for your token claims and signature, or by usig a JWT library of your choice.
To validate a token through Daily's REST API, make a GET request to https://api.daily.co/v1/meeting-tokens/[DAILY_MEETING_TOKEN]. The request will look as follows:
If the token is valid, the response code will be 200 and the response body will contain an object containing the token properties. If the token is not valid, an error response will be returned.
Conclusion
In this guide, we've covered basic guidelines for obtaining, using, and validating Daily meeting tokens. Please contact us if you have any questions about using meeting tokens in your application.