Skip to content

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:

PermissionsScopesUse it for
Read onlynamespace.read, distribution.read, deployment.read, domain.read, analytics.read, logs.readDashboards and reports
Publish previewsdistribution.read, deployment.read, deployment.writePull-request previews. Cannot change the live site
Publish and promotethe above, plus deployment.promoteRelease jobs that make deployments live
Customany scopes you holdAnything 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 ​

  1. Open Access tokens in the sidebar, at https://app.edge.deca-dev.com/edge/{workspaceId}/access-tokens.
  2. Select Create token.
  3. Enter a Name that says what will use it, such as github-actions.
  4. Choose Permissions and Expiration. Choosing No expiration shows a warning.
  5. Select Review. Check the name, workspace, scopes and expiry.
  6. 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 ​

text
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.
bash
edge tokens create
bash
# 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:

json
{
  "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:

json
{
  "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:

bash
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.

text
List my Edge access tokens, then revoke the one called old-ci.
bash
edge tokens ls
edge tokens revoke 01M4B2C9QW7RZJ5K8XYV3NTPDA
bash
curl -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.

Next ​