Access Control

Access Control

#Overview

The Access Control feature allows you to easily manage who is and isn't allowed to log in to your application. Access can be gated in 2 ways: explicitly allowing only certain emails and domains through with Allow List, or blocking certain emails and domains with Block List.

This feature is compatible with some OAuth providers (see Social Login), and not currently compatible with WebAuthn.

#Allow List

The Allow List lets you specify emails and domains that can access your site. The max list size for Allow List is 20k entries. Sample use cases are mailing lists, private organizations or message boards.

note

By default this list is empty, which means that everyone is allowed access, however once valid entries are specified in this list, only those emails + domains will be allowed to access your application.

#Block List

The Block List lets you specify emails and domains you wish to block from accessing your application. The max list size for Block List is also 20k entries. Useful for most applications, forums, message boards, social media, etc.

important

The entries in this list take precedence over the entries in the Allow List. If an email (or domain wildcard) is specified in the Block List would otherwise be granted access by the Allow List, the email would still be blocked.

#Formatting

  • Accepts email addresses or domain wildcards
  • Separate entries with spaces, commas, or line breaks
  • Pulling from a CRM? Export emails as a single-column CSV; copy + paste

#Social Login

We are only able to gate email access for OAuth providers that return a user's email inside the OAuth user info response.

The following is a list of OAuth providers that require additional steps or verification for your application to support email access.

  • Twitter
  • Microsoft
  • Bitbucket
  • LinkedIn

#Usage

In order to interact with the email access control list for your application, you will need a Secret Key and Client ID.

To obtain the required information, follow the steps below:

  1. Navigate to a Magic app from the main dashboard landing page.
  2. Save the SECRET KEY in the API Keys section.
  3. Save the cid query param from the URL.
    • Example: ⁠https://dashboard.magic.link/app?cid=<this_is_the_client_id>

#Get Access Control Lists

In the Headers section, pass the Secret Key for the X-Magic-Secret-Key value. This will return a list of emails in your allow list and block list.

Bash
01curl --request GET \
02  --url https://api.magic.link/v1/api/magic_client/access_control \
03  --header 'x-magic-secret-key: sk_live_06FC010DA25ED4F2'

#Create new Access Control Lists

In the Headers section, pass the Secret Key for the X-Magic-Secret-Key value. In the body of the JSON, fill in your Client ID as the target_client_id and the list of emails to use as the allow list and block list. This will clear any pre-existing lists you have already created.

Bash
01curl --request PUT \
02  --url https://api.magic.link/v1/api/magic_client/access_control \
03  --header 'Content-Type: application/json' \
04  --header 'x-magic-secret-key: sk_live_06FC010DA25ED4F2' \
05  --data '{
06	"target_client_id": "3LDeve5f56ouY_tN-jLJlop_hkLI1LLTNG8abaCD42E=",
07	"emails": {
08		"allow_list": [
09			"[email protected]",
10			"[email protected]"
11		],
12		"block_list": [
13			"[email protected]"
14		]
15	}
16}'

#Update Access Control Lists

In the Headers section, pass through the Secret Key in the X-Magic-Secret-Key value. In the body of the JSON, fill in your Client ID as the target_client_id and the list of emails to append to the application’s allow list and block list.

Bash
01curl --request PATCH \
02  --url https://api.magic.link/v1/api/magic_client/access_control \
03  --header 'Content-Type: application/json' \
04  --header 'x-magic-secret-key: sk_live_06FC010DA25ED4F2' \
05  --data '{
06	"target_client_id": "3LDeve5f56ouY_tN-jLJlop_hkLI1LLTNG8abaCD42E=",
07	"emails": {
08		"allow_list": [
09			"[email protected]"
10		],
11		"block_list": [
12			"[email protected]"
13		]
14	}
15}'

#Remove Emails From Access Control Lists

In the Headers section, pass the Secret Key for the X-Magic-Secret-Key value. In the body of the JSON, fill in your Client ID as the target_client_id and the list of emails to remove from the application’s allow list and block list.

Bash
01curl --request DELETE \
02  --url https://api.magic.link/v1/api/magic_client/access_control \
03  --header 'Content-Type: application/json' \
04  --header 'x-magic-secret-key: sk_live_06FC010DA25ED4F2' \
05  --data '{
06	"target_client_id": "3LDeve5f56ouY_tN-jLJlop_hkLI1LLTNG8abaCD42E=",
07	"emails": {
08		"allow_list": [
09			"[email protected]"
10		],
11		"block_list": [
12			"[email protected]"
13		]
14	}
15}'