Authenticate to the Jira Cloud REST API v3 using an API token (Basic auth) or OAuth 2.0 3LO, and resolve the cloudId for app-scoped calls

Documented steps

1. Decide the auth mode. Personal scripts/internal automation: Atlassian account email + API token via Basic auth. Distributed apps/integrations: OAuth 2.0 3LO. Atlassian's guidance is that apps which collect user API tokens do not meet its security requirements — build integrations on OAuth 2.0 (3LO) or Forge, not on collected tokens.
2. API token path: create a token at https://id.atlassian.com/manage-profile/security/api-tokens, then build the credential string 'user@example.com:API_TOKEN' and base64-encode it. Send header 'Authorization: Basic <base64>'. Base URL is https://your-domain.atlassian.net/rest/api/3/...
3. Verify the token works: GET https://your-domain.atlassian.net/rest/api/3/myself -H 'Authorization: Basic <base64>' -H 'Accept: application/json'. A 200 with accountId confirms auth; 401 means bad token; 403 means auth is fine but permission is missing.
4. OAuth 2.0 3LO path: redirect the user to https://auth.atlassian.com/authorize?audience=api.atlassian.com&client_id=<id>&scope=<space-separated scopes>&redirect_uri=<uri>&state=<csrf>&response_type=code&prompt=consent
5. Exchange the returned code: POST https://auth.atlassian.com/oauth/token with JSON {grant_type:'authorization_code', client_id, client_secret, code, redirect_uri}. Include the 'offline_access' scope in step 4 if you need a refresh token.
6. Resolve the site: GET https://api.atlassian.com/oauth/token/accessible-resources -H 'Authorization: Bearer <access_token>'. The response is an array; each entry's 'id' is the cloudId for that Jira site.
7. Call the API with the cloudId base URL: https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/... — this differs from the Basic-auth base URL and is a frequent source of 404s when the two are mixed up.
8. Refresh tokens: POST https://auth.atlassian.com/oauth/token with {grant_type:'refresh_token', client_id, client_secret, refresh_token}. Persist the NEW refresh token returned by every refresh before using it.
9. Choose scopes: classic scopes read:jira-work, write:jira-work, read:jira-user cover most issue automation; granular scopes (read:issue:jira, write:issue:jira, read:jql:jira) are finer-grained. Effective permissions are always the intersection of app scopes and the acting user's own Jira permissions.