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.solarandsales-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
| Status | Meaning | Fix |
|---|---|---|
401 Unauthorized | Missing, malformed, expired, or revoked key | Check the x-api-key header is present and correct for this environment |
403 Forbidden | Key is valid but lacks access to the resource or capability | Check 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_REQUIREDpostMessage 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.

