Authentication & API Keys

Use these credentials for API v2 and embedded UI:

  • API key: server-to-server REST calls via x-api-key; can expire or be revoked.
  • Impersonation token: iframe authentication via authToken; expires in 1 hour.

API keys (REST API)

Send your API key in the x-api-key header:

curl "https://sales-sandbox-api.artemis.solar/external/v2/projects" \
  -H "x-api-key: $ARTEMIS_API_KEY"
  • Where to get one: create a key in Settings → API Keys if you have access, or ask your Artemis administrator. Keys are scoped to a single organization and a single environment.
  • Sandbox vs. production: you'll receive separate keys for sales-sandbox-api.artemis.solar and sales-api.artemis.solar. They are not interchangeable.
  • Access: requests follow the associated user's permissions and are scoped to your organization.
  • Expiration and revocation: expired or revoked keys stop authenticating. Replace them in your integration when rotating credentials.

Store API keys server-side in a secret manager or environment variable. Never expose them in browser code, mobile apps, or public repositories. Revoke and replace leaked keys; ask your administrator if you cannot manage them.

User-authorized MCP OAuth bearer tokens work only where listed in API Reference v2; other operations require an API key. Impersonation tokens authenticate embedded UI, not REST calls.

Authentication failures

StatusMeaningFix
401 UnauthorizedMissing, malformed, expired, or revoked keyCheck the x-api-key header is present and correct for this environment
403 ForbiddenKey is valid but lacks access to the resource or capabilityCheck permissions, resource access, and any required capability

For the full list of status codes and how to handle each, see Error Handling. Hitting the request limit returns 429; see Rate Limits.

Impersonation tokens (embedded UI)

An impersonation token opens Proposal or Design Mode in an iframe without a login screen, as the user associated with your API key.

Generating a token

Call POST /users/impersonate with your API key:

curl -X POST "https://sales-sandbox-api.artemis.solar/users/impersonate" \
  -H "x-api-key: $ARTEMIS_API_KEY"

The response contains a token you then pass to the iframe via ?authToken=.... Artemis accepts it only inside an iframe or on the Safari /impersonate popup; a top-level link with ?authToken= does not sign in.

Enable Allow this API key to impersonate the user in Settings → API Keys (off by default). The organization must also allow impersonation. On 403, check the key first, then ask Artemis engineering to enable the organization.

Token lifetime & refresh

  • Tokens expire after 1 hour. For long-lived iframe sessions, refresh before expiry or react to the AUTH_REQUIRED postMessage the iframe emits when a token is rejected (see Iframe Integration).
  • Generate tokens server-side to keep your API key out of the browser.

Which credential do I use?

  • API key: backend REST calls, including projects, reads, team/user management, and token generation.
  • Impersonation token: embedded Artemis UI without a login screen.