Authorization for Id Mapping

In order to prevent abuse, you must authenticate yourself before you can use the Id Mapping APIs. This page explains the authorization process required to access the migration API endpoints.

Migration API Authorization

Basic Authentication

The migration API uses basic authentication for secure access to Id Mapping endpoints.

Learn more: Basic auth for REST APIs
Username: The email address of your Atlassian Cloud account
Password: Your cloud API token
Required permissions: Site or org admin permissions on the destination cloud site

Setting Up Cloud Authentication

Verify admin access: Ensure your account has site or org admin permissions on the destination cloud site
Generate API token: Learn how to create an API token
Use credentials: Your email as username and API token as password

Example Authentication Header

1
2
# Basic auth with email and API token
Authorization: Basic <base64-encoded-email:api-token>

# Example with curl
curl -X POST \
  https://api.atlassian.com/migrations/reports/v1/id-mappings/trigger \
  -H "Authorization: Basic $(echo -n 'user@example.com:your-api-token' | base64)" \
  -H "Content-Type: application/json"

Security Best Practices

For Cloud API Tokens

Rotate regularly: Change your API tokens periodically
Limit scope: Use tokens with minimal required permissions
Store securely: Never commit tokens to code repositories
Monitor usage: Review API token usage in your Atlassian account

For Server/DC Access

Use dedicated service accounts: Create specific accounts for API access
Enable 2FA: Use two-factor authentication where possible
Regular audits: Review and rotate credentials regularly
Network security: Ensure secure network connections (HTTPS/SSL)

Common Authentication Issues

401 Unauthorized

Possible causes:

Incorrect email or API token
Expired API token
Account lacks required permissions

Solutions:

Verify your email and regenerate API token
Confirm admin permissions on the cloud site
Check token hasn't been revoked

403 Forbidden

Possible causes:

Account lacks site/org admin permissions
API token has insufficient scope
IP restrictions or security policies

Solutions:

Request admin permissions from site administrator
Verify API token permissions
Check network and security configurations

Testing Your Authentication

You can test your authentication setup using a simple API call:

1
2
# Test authentication with status endpoint
curl -X GET \
  "https://api.atlassian.com/migrations/reports/v1/id-mappings/test-job-id" \
  -H "Authorization: Basic $(echo -n 'your-email@example.com:your-api-token' | base64)" \
  -H "Content-Type: application/json"

# Expected response for invalid job ID (but valid auth):
# {"status": 404, "errorMessage": "Job not found..."}

# If auth is invalid, you'll get:
# {"status": 401, "errorMessage": "Unauthorized"}

Next Steps

Once you have proper authorization configured: