Create a personal access token
A personal access token (edge_pat_…) lets a script, a CI job, or an agent call Edge as you, without a browser sign-in. You choose what it may do and when it stops working, and you can revoke it at any time.
Three rules shape every token:
- It never has more than you. You can only grant scopes your own role has. A token never carries
token.admin. - It works in one workspace, the one you create it in. A request for another workspace returns 403.
- It is shown once. Edge stores only a hash. If you lose the token, revoke it and create another.
Choose its permissions and expiry
Pick the narrowest option that does the job:
| Permissions | Scopes | Use it for |
|---|---|---|
| Read only | namespace.read, distribution.read, deployment.read, domain.read, analytics.read, logs.read | Dashboards and reports |
| Publish previews | distribution.read, deployment.read, deployment.write | Pull-request previews. Cannot change the live site |
| Publish and promote | the above, plus deployment.promote | Release jobs that make deployments live |
| Custom | any scopes you hold | Anything else |
Expiry can be 7, 30 (the default), 60 or 90 days, one year, a date you pick within a year, or no expiration. A token that never expires keeps its access until someone revokes it, so prefer an expiry and replace the token before it runs out.
Create it in the console
- Open Access tokens in the sidebar, at
https://app.edge.deca-dev.com/edge/{workspaceId}/access-tokens. - Select Create token.
- Enter a Name that says what will use it, such as
github-actions. - Choose Permissions and Expiration. Choosing No expiration shows a warning.
- Select Review. Check the name, workspace, scopes and expiry.
- Select Create token, then copy the token. This is the only time it is shown.
Creating a token does not change any site.
Create it with an agent, the CLI, or the API
Create a personal access token called github-actions that can publish previews
and expires in 90 days. Show me the summary before you create it.edge tokens create# 1. Ask for the summary. Nothing is created yet.
curl -s -X POST https://api.edge.deca-dev.com/v1/tokens \
-H "Authorization: Bearer $EDGE_SIGN_IN_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"github-actions","preset":"publish_previews","expiration":"90d"}'
# 2. After checking it, send the same body with "confirm": true.
curl -s -X POST https://api.edge.deca-dev.com/v1/tokens \
-H "Authorization: Bearer $EDGE_SIGN_IN_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"github-actions","preset":"publish_previews","expiration":"90d","confirm":true}'The first call returns the summary you confirm:
{
"confirmation_required": true,
"summary": {
"name": "github-actions",
"namespace_id": "5c1e2a90-3f4b-4d6e-9a17-2b8c0d4e6f13",
"scopes": ["deployment.read", "deployment.write", "distribution.read"],
"expires_at": "2027-01-08T12:00:00Z"
}
}The second returns the token, once:
{
"id": "01M4B2C9QW7RZJ5K8XYV3NTPDA",
"name": "github-actions",
"token": "edge_pat_3kT9vQ…",
"hint": "edge_pat_…7QxZ",
"status": "active",
"notice": "Copy the token now. Edge stores only its hash and cannot show it again."
}The agent runs edge_token_create. It must show you the summary and wait for your answer before it calls the tool again with confirm. A personal access token cannot create another one: create tokens from a signed-in session.
For a custom set of scopes, send "scopes": ["deployment.read", "deployment.write"] instead of preset. For a fixed date, send "expires_at": "2026-12-31" instead of expiration. For no expiry, send "expiration": "never"; the summary then carries a warning.
Use it
Send it as a bearer token, exactly like a sign-in token:
curl -s https://api.edge.deca-dev.com/v1/distributions \
-H "Authorization: Bearer edge_pat_3kT9vQ…"It works on the HTTP API and on the MCP server at https://mcp.edge.deca-dev.com for clients that let you set an Authorization header. For the CLI and CI, store it as EDGE_TOKEN; see Publish from GitHub Actions.
List and revoke tokens
The Access tokens page lists your tokens with their scopes, expiry, last use and status. Select Revoke on a row to stop the token immediately; anything using it starts getting 401. Revoking cannot be undone.
List my Edge access tokens, then revoke the one called old-ci.edge tokens ls
edge tokens revoke 01M4B2C9QW7RZJ5K8XYV3NTPDAcurl -s https://api.edge.deca-dev.com/v1/tokens -H "Authorization: Bearer $EDGE_SIGN_IN_TOKEN"
curl -s -X DELETE https://api.edge.deca-dev.com/v1/tokens/01M4B2C9QW7RZJ5K8XYV3NTPDA \
-H "Authorization: Bearer $EDGE_SIGN_IN_TOKEN"The agent runs edge_token_list and edge_token_revoke. The list never contains the tokens themselves, only a hint such as edge_pat_…7QxZ.
Admins with token.admin can list everyone's tokens in the organization (GET /v1/tokens?all=true) and revoke any of them. Do this when someone leaves or changes role: a token keeps the scopes it was created with until it expires or is revoked.