# Upload source maps

Get a SENTRY_AUTH_TOKEN for sentry-cli and withSentryConfig, a long-lived one, a one-project token of at most an hour, or one from a GitHub workflow without a stored secret, and see how maps are applied.

`withSentryConfig`, the bundler plugins and `sentry-cli sourcemaps inject` and `upload` upload to
Error Tracking with nothing changed but `SENTRY_AUTH_TOKEN`: the token carries the Error Tracking
URL and your organization. An app deployed on Deutsche Cloud, or built in a connected CI environment,
gets a token on every build without any of this (see [Connect an app](connect-an-app.md) and
[Connect a CI environment](connect-a-ci-environment.md)). Replace _project-id_ with the project's
id.

## Choose a token

| Token                         | Lifetime                                                                 | May                                                                           |
| ----------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Auth token (**Create token**) | Your organization's default access-key lifetime, or the days you ask for | Everything you may do in Error Tracking, in every project, nothing outside it |
| Upload token                  | 60 seconds to an hour, never beyond the credential that asked for it     | Upload source maps to one project, and the reads `sentry-cli` needs there     |

## Create an auth token

The token is an access key of yours, limited to Error Tracking actions (`errors:*`). It is shown
once. It is listed under **Access keys** in Identity, where you revoke it.

Prerequisites: `iam:CreateAccessKey` and `errors:UploadSourceMaps`, both on their service
(`rn:ews::<organization id>:iam:*` and `rn:ews:de1:<organization id>:errors:*`), since the token
works in every project. The console offers the button with `errors:UploadSourceMaps` on the
project alone, and the request is then refused. Without them, the **Setup** tab
says "A token is an access key of yours capped to Error Tracking: creating one needs
iam:CreateAccessKey and errors:UploadSourceMaps." In the console, also `errors:ListProjects` on the
project to open it.

**Console**
1. Open the project, then the **Setup** tab.
2. Under **Source maps**, choose **Create token**.
3. Copy the token under **SENTRY_AUTH_TOKEN (CI secret)**. It is not shown again.

A token created in the console expires after your organization's default access-key lifetime
(90 days unless your organization changed it).

**CLI**
```sh
dcloud errors auth-tokens create --description web-ci --expires-in-days 90
```

**API**
```http
POST /errors/api/auth-tokens
{ "description": "web-ci", "expiresInDays": 90 }
```

The answer is `201` with `token`, `accessKeyId` and `expiresAt`.

- `400` when `expiresInDays` is more than your organization allows ("expiresInDays is …; this
  organization allows at most … days").
- `409` when your access-key quota is used up.

## Create an upload token

An upload token may upload source maps to one project only. It is an access key of the person or
role that asked, revoked when it expires.

Prerequisites: `errors:UploadSourceMaps` on the project.

**Console:** not available. The console creates auth tokens only.
**CLI**
```sh
dcloud errors auth-tokens create-upload-token project-id --ttl-seconds 900
```

**API**
```http
POST /errors/api/projects/project-id/upload-token
{ "ttlSeconds": 900 }
```

The answer is `201` with `token`, `expiresAt`, and `org`, `project` and `url` for `sentry-cli`,
and `dsn`, the project's managed DSN (null while nothing is connected to the project).
Without `ttlSeconds` the token lasts an hour. When you call with a temporary access key that
expires sooner, the token expires with it.

## Get an upload token in a GitHub workflow

A workflow on GitHub's own runners can get an upload token without a stored secret:

1. Register GitHub as an identity provider and create a role whose trust policy names your
   repository (see [Deploy from GitHub Actions](/docs/iam/guide/deploy-from-github-actions)).
2. Give the role a policy that allows `errors:UploadSourceMaps`, `errors:ListProjects` and
   `errors:ListReleases` on the project.
3. In the job, exchange GitHub's token for a temporary access key of the role, and that for an
   upload token. The **Setup** tab shows this workflow with your values under
   **Building on GitHub Actions? No stored secret with OIDC**.

```yaml
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      EWS_API_URL: https://console.example.com
      EWS_ROLE_RN: rn:ews::org-EXAMPLE1234:iam:role/role-id
    steps:
      - uses: actions/checkout@v4
      - name: Error Tracking upload token (OIDC, no stored secret)
        run: |
          AUD=$(jq -rn --arg a "$EWS_API_URL" '$a|@uri')
          OIDC_TOKEN=$(curl -sS --fail-with-body \
            -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUD" | jq -r .value)
          CREDS=$(curl -sS --fail-with-body -X POST "$EWS_API_URL/iam/api/sts/assume-role-with-web-identity" \
            -H 'content-type: application/json' \
            -d "$(jq -n --arg role "$EWS_ROLE_RN" --arg t "$OIDC_TOKEN" '{roleRn: $role, webIdentityToken: $t, durationSeconds: 900}')")
          KEY=$(jq -r .data.accessKey <<<"$CREDS")
          echo "::add-mask::$KEY"
          OUT=$(curl -sS --fail-with-body -X POST "$EWS_API_URL/errors/api/projects/project-id/upload-token" \
            -H "Authorization: EWS-ACCESS-KEY $KEY" -H 'content-type: application/json' \
            -d '{"ttlSeconds": 900}')
          TOKEN=$(jq -r .data.token <<<"$OUT")
          echo "::add-mask::$TOKEN"
          echo "SENTRY_AUTH_TOKEN=$TOKEN" >> "$GITHUB_ENV"
      - run: npm ci && npm run build
```

The role's key lasts 15 minutes (`durationSeconds: 900`), so the upload token does too.

## How maps are applied

- Frames are matched to their maps by debug ID, which `withSentryConfig`, the bundler plugins and
  `sentry-cli sourcemaps inject` write. Uploads by release and URL (`~/static/js/app.js.map`) work
  as well.
- A frame is named after the function that encloses its line in your source, also when the
  minifier inlined that function into its caller: the frame then reads
  `totalOf (inlined into onClick)`.
- A map is applied when the event arrives. A map uploaded later does not change events already
  received, or how they were grouped. A frame whose map was missing is marked **no source map** on
  the issue page and keeps its minified position: upload a release's maps before you deploy it.

## Related

- [Connect an app](connect-an-app.md)
- [Issues and grouping](issues-and-grouping.md)
- `errors.auth-tokens.create` · `dcloud errors auth-tokens create-upload-token`
