# Embed Login API

Canvas allows your to generate links that log your users into your Canvas account and optionally redirect them to a specific dashboard.

If you want to use this API please request that Canvas enable this for you.

### Guide

Navigate to your [settings page](https://canvasapp.com/team_settings) and click "Create key" under the Embed API section. Save this key **securely**. This key has the ability to grant access to your account. This key cannot be retrieved once generated.

<figure><img src="https://3313014851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy7E9BPGuy0SmG7YF1yur%2Fuploads%2F22LHowxmuJcAzoUeczTD%2FScreenshot%202023-11-09%20at%208.18.35%20PM.png?alt=media&#x26;token=bb1f26a6-098c-49c7-9ebc-586b2de69bbc" alt=""><figcaption></figcaption></figure>

### Implement the backend

Using the signing key your application backend can generate tokens that grant bearers permission to login to Canvas. You can use one of Canvas' [clients](https://github.com/canvas/embed) to generate the tokens or use them as a guide to implement your own generation.

The key is generated using [`libsodium`](https://libsodium.gitbook.io/doc/secret-key_cryptography/secretbox) .&#x20;

If you implement your own backend we recommend using `libsodium` to sign the tokens as well. You can follow this guide.

The key you receive from Canvas is actually an `[identifier].[key]` pair where the `key` is your secret key and the `identifier` is a unique identifier for this key in Canvas. You use the `key` portion to generate your encrypted payloads and simply include the `identifier` in the last step.

Canvas expects the encrypted message payload to be a JSON string with the following structure:

```
{
    email: [email of the user in Canvas],
    exp: [unix time in seconds the token should be valid until],
    userId: [optional identifier for the user],
    firstName: [optional first name of user],
    lastName: [optional last name of user],
}
```

This payload should be [encrypted](https://libsodium.gitbook.io/doc/secret-key_cryptography/secretbox#combined-mode) using the `key` portion of the signing key and a `nonce`

The encrypted payload and the nonce should then unpacked from `bytes` into `hex` for transmission.

This should then be included in the following token payload to Canvas:<br>

```
{
    message: [hex encoded payload],
    nonce: [hex encoded nonce],
    keyId: [key identifier from Canvas signing key],
}
```

Stringify and `base64` encode this to get your token.

### Implement the frontend

On the frontend you only need to add a link with the following structure:

```
https://canvasapp.com/signed_login?token=[generated token]&redirect=/canvas/your_canvas_id
```

The `redirect` portion is optional. If not included the user will be redirected to the Canvas homepage.

### Canvas setup

Any emails that you want to login with this method will need to be invited to your Canvas team beforehand.&#x20;