DocsAuthentication and keys

Get started

Authentication and keys

Every key belongs to an account. An account holds up to 10 active keys, which share its plan and its daily credits. Name a key for the server or app that uses it, rotate it without downtime, and revoke it the moment it leaks.

Send the key in a header

Use either header. Both accept the same creo_ key.

curl https://itscreo.com/v1/account -H "x-api-key: $CREO_KEY"
curl https://itscreo.com/v1/account -H "Authorization: Bearer $CREO_KEY"

Keys in the URL are refused with 400 KEY_IN_QUERY, because URLs end up in logs, proxies and browser history.

Which endpoints need a key

  • No key: creating an account's first key, plans, status, account recovery, and the demo tickers (up to 20 calls a day per IP).
  • Key required: scoring your own holdings, and everything under /v1/account.

Store it once

Creo keeps only a SHA-256 hash of each key and shows the secret once, when it is created. Afterwards you see its prefix, such as creo_Xk3a9Qf, which is enough to tell keys apart in a list. Keep the secret in a secret store or an environment variable such as CREO_KEY. Each IP address can create 5 new accounts a day.

Create an account and its first key

Pass an optional name, and an optional email to use for account recovery.

POST/v1/keys

Mint a free API key No key needed

Returns a new key once; Creo stores only its hash. No auth needed. Limited to 5 keys per IP per UTC day, so reuse your key (for example from a CREO_KEY environment variable) instead of minting per run.

Request body

Example

curl -X POST https://itscreo.com/v1/keys \
  -H "content-type: application/json" \
  -d '{}'

Responses

  • 201Successful Response IssuedKey
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 429RATE_LIMITED: 5 new keys per IP per day Error
Response fields
keystringrequired

The secret. Shown once; Creo stores only a hash.

idstringrequired
namestringnullable
key_prefixstringrequired
planstringrequired
daily_call_limitintegerrequired
max_positionsintegerrequired
created_atdatetimerequired

Manage keys

List keys to see each one's name, prefix, created and last-used times, and state: active, expiring (inside a rotation overlap), expired or revoked. Any active key on the account can manage the others.

GET/v1/account/keys

List this account's keys Requires a key

Every key on the account with its prefix, created and last-used times and state.

Example

curl https://itscreo.com/v1/account/keys \
  -H "x-api-key: $CREO_KEY"

Responses

  • 200Successful Response KeyList
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
Response fields
keysarray of KeyInforequired
Child fields
idstringrequired
namestringrequired
key_prefixstringrequired
stateenumrequired

One of active, expiring, expired, revoked

created_atdatetimerequired
last_used_atdatetimerequired
expires_atdatetimerequired

Set while a rotated key overlaps with its replacement.

revoked_atdatetimerequired
currentbooleanrequired

True for the key that made this request.

max_active_keysinteger

Default 10

POST/v1/account/keys

Create another key on this account Requires a key

Shares the account's plan and daily credits. The secret is returned once.

Request body

Example

curl -X POST https://itscreo.com/v1/account/keys \
  -H "x-api-key: $CREO_KEY" \
  -H "content-type: application/json" \
  -d '{}'

Responses

  • 201Successful Response IssuedKey
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
  • 409KEY_LIMIT: 10 active keys, or LAST_KEY Error
Response fields
keystringrequired

The secret. Shown once; Creo stores only a hash.

idstringrequired
namestringnullable
key_prefixstringrequired
planstringrequired
daily_call_limitintegerrequired
max_positionsintegerrequired
created_atdatetimerequired

POST/v1/account/keys/{key_id}/rotate

Rotate a key, optionally keeping the old one working for a while Requires a key

Issues a replacement with the same name. With expires_in_hours the old key keeps working until then; with 0 (the default) it stops immediately.

path parameter key_id:

Request body

Example

curl -X POST https://itscreo.com/v1/account/keys/{key_id}/rotate \
  -H "x-api-key: $CREO_KEY" \
  -H "content-type: application/json" \
  -d '{}'

Responses

  • 201Successful Response RotatedKey
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
  • 404KEY_NOT_FOUND: not a key on this account Error
Response fields
new_keyIssuedKeyrequired
Child fields
keystringrequired

The secret. Shown once; Creo stores only a hash.

idstringrequired
namestringnullable
key_prefixstringrequired
planstringrequired
daily_call_limitintegerrequired
max_positionsintegerrequired
created_atdatetimerequired
old_keyKeyInforequired
Child fields
idstringrequired
namestringrequired
key_prefixstringrequired
stateenumrequired

One of active, expiring, expired, revoked

created_atdatetimerequired
last_used_atdatetimerequired
expires_atdatetimerequired

Set while a rotated key overlaps with its replacement.

revoked_atdatetimerequired
currentbooleanrequired

True for the key that made this request.

DELETE/v1/account/keys/{key_id}

Revoke a key Requires a key

Stops the key at once. The account's last active key cannot be revoked.

path parameter key_id:

Example

curl -X DELETE https://itscreo.com/v1/account/keys/{key_id} \
  -H "x-api-key: $CREO_KEY"

Responses

  • 200Successful Response KeyInfo
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
  • 404KEY_NOT_FOUND: not a key on this account Error
  • 409KEY_LIMIT: 10 active keys, or LAST_KEY Error
Response fields
idstringrequired
namestringrequired
key_prefixstringrequired
stateenumrequired

One of active, expiring, expired, revoked

created_atdatetimerequired
last_used_atdatetimerequired
expires_atdatetimerequired

Set while a rotated key overlaps with its replacement.

revoked_atdatetimerequired
currentbooleanrequired

True for the key that made this request.

Rotating without downtime

Rotation issues a replacement with the same name. Set expires_in_hours (up to 168) to keep the old key working while you deploy the new one; it stops at that time with no further action. With 0, the default, the old key stops at once. An expired or revoked key cannot be rotated again to extend its life.

curl -X POST https://itscreo.com/v1/account/keys/$KEY_ID/rotate \
  -H "x-api-key: $CREO_KEY" -H "content-type: application/json" \
  -d '{"expires_in_hours": 24}'

Revoking

Revoking stops a key immediately. The account's last active key cannot be revoked (409 LAST_KEY), so an account never locks itself out: create or rotate to a new key first.

Plan, usage and the request log

Reading the account is free and never charged. Usage covers the last 30 UTC days: calls attempted and credits charged per day, for the whole account or one key with ?key_id=. The request log keeps every keyed, scored call (time, route, status, credits and request ID) for 30 days, up to 1,000 per account. Every response carries its request ID in the X-Request-Id header; quote it when you contact support.

GET/v1/account

Account Requires a key

Example

curl https://itscreo.com/v1/account \
  -H "x-api-key: $CREO_KEY"

Responses

  • 200Successful Response AccountStatus
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
Response fields
account_idstringrequired
key_idstringrequired
key_namestringrequired
key_prefixstringrequired
recovery_emailstringrequired
recovery_availablebooleanrequired

False while Creo has no outgoing email configured.

planPlanrequired
Child fields
idstringrequired
namestringrequired
monthly_usdintegerrequired
daily_call_limitintegerrequired
max_positionsintegerrequired
summarystringrequired
featuresarray of PlanFeature
Child fields
textstringrequired
enforced_byarray of stringrequired

How Creo enforces it: gate:<feature> (a plan check on the route), limit:daily_call_limit or limit:max_positions, includes:<plan>, included (every key gets it) or terms (the license, not a technical limit).

subscription_planstringrequired
subscription_statusstringrequired
current_period_enddatetimerequired
cancel_at_period_endbooleanrequired
can_manage_billingbooleanrequired
calls_used_todayintegerrequired
reset_atdatetimerequired

GET/v1/account/usage

Daily calls and credits for 30 days, and recent requests Requires a key

Account-wide by default; pass key_id for one key. Free, never charged.

query parameter key_id:

Example

curl https://itscreo.com/v1/account/usage \
  -H "x-api-key: $CREO_KEY"

Responses

  • 200Successful Response AccountUsage
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
Response fields
key_idstringrequired

The key filtered on, or null for every key.

daysarray of UsageDayrequired

The last 30 UTC days, oldest first.

Child fields
daydaterequired
callsintegerrequired

Scored calls attempted, including rate-limited ones.

creditsintegerrequired

Credits charged after refunds.

requestsarray of LoggedRequestrequired

The 100 most recent scored calls.

Child fields
atdatetimerequired
key_idstringrequired
key_prefixstringrequired
methodstringrequired
routestringrequired
statusintegerrequired
creditsintegerrequired
request_idstringrequired
log_retentionstring

Default "Scored calls from the last 30 days, up to 1,000 per account."

Account recovery

Add a recovery email to the account. If you lose every key, request a link at /account; it works once, for 30 minutes, and mints a new key on the same account, with the same plan and billing. Your other keys keep working, so revoke any you have lost afterwards. The recovery request always answers 202, whether or not the email matches an account, so it cannot reveal who holds one. The email is used for nothing else.

Recovery email is optional and off by default. While it is off, /v1/account reports recovery_available: false and a recovery request returns 503 RECOVERY_UNAVAILABLE.

Keep a backup key

Any active key on an account can manage every other key, so a second key is a complete recovery path that works today. Create one named Backup key, store it in your password manager, and use it only to sign in at /account and rotate or revoke the rest if you lose your working key.

PUT/v1/account/recovery-email

Set or remove the account's recovery email Requires a key

Request body

emailstringrequired

Where recovery links go; null removes it.

Example

curl -X PUT https://itscreo.com/v1/account/recovery-email \
  -H "x-api-key: $CREO_KEY"

Responses

  • 200Successful Response AccountStatus
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
Response fields
account_idstringrequired
key_idstringrequired
key_namestringrequired
key_prefixstringrequired
recovery_emailstringrequired
recovery_availablebooleanrequired

False while Creo has no outgoing email configured.

planPlanrequired
Child fields
idstringrequired
namestringrequired
monthly_usdintegerrequired
daily_call_limitintegerrequired
max_positionsintegerrequired
summarystringrequired
featuresarray of PlanFeature
Child fields
textstringrequired
enforced_byarray of stringrequired

How Creo enforces it: gate:<feature> (a plan check on the route), limit:daily_call_limit or limit:max_positions, includes:<plan>, included (every key gets it) or terms (the license, not a technical limit).

subscription_planstringrequired
subscription_statusstringrequired
current_period_enddatetimerequired
cancel_at_period_endbooleanrequired
can_manage_billingbooleanrequired
calls_used_todayintegerrequired
reset_atdatetimerequired

PUT/v1/account/recovery-email

Set or remove the account's recovery email Requires a key

Request body

emailstringrequired

Where recovery links go; null removes it.

Example

curl -X PUT https://itscreo.com/v1/account/recovery-email \
  -H "x-api-key: $CREO_KEY"

Responses

  • 200Successful Response AccountStatus
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 401AUTHENTICATION_REQUIRED: missing or invalid key Error
Response fields
account_idstringrequired
key_idstringrequired
key_namestringrequired
key_prefixstringrequired
recovery_emailstringrequired
recovery_availablebooleanrequired

False while Creo has no outgoing email configured.

planPlanrequired
Child fields
idstringrequired
namestringrequired
monthly_usdintegerrequired
daily_call_limitintegerrequired
max_positionsintegerrequired
summarystringrequired
featuresarray of PlanFeature
Child fields
textstringrequired
enforced_byarray of stringrequired

How Creo enforces it: gate:<feature> (a plan check on the route), limit:daily_call_limit or limit:max_positions, includes:<plan>, included (every key gets it) or terms (the license, not a technical limit).

subscription_planstringrequired
subscription_statusstringrequired
current_period_enddatetimerequired
cancel_at_period_endbooleanrequired
can_manage_billingbooleanrequired
calls_used_todayintegerrequired
reset_atdatetimerequired

POST/v1/account/recover

Email a recovery link No key needed

No key needed. Always 202 when recovery is on, whether or not the email matches an account, so it cannot reveal who holds one.

Request body

emailstringrequired

Example

curl -X POST https://itscreo.com/v1/account/recover \
  -H "content-type: application/json" \
  -d '{}'

Responses

  • 202Successful Response
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 429RATE_LIMITED: 5 requests per IP per day Error
  • 503RECOVERY_UNAVAILABLE: outgoing email is off Error

POST/v1/account/recover/redeem

Mint a new key from a recovery link No key needed

Single use, valid 30 minutes. Existing keys keep working; revoke lost ones after.

Request body

tokenstringrequired

The token from the link.

Example

curl -X POST https://itscreo.com/v1/account/recover/redeem \
  -H "content-type: application/json" \
  -d '{}'

Responses

  • 201Successful Response IssuedKey
  • 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged. Error
  • 400KEY_IN_QUERY: send the key in a header, not the URL Error
  • 410RECOVERY_LINK_INVALID: expired or already used Error
Response fields
keystringrequired

The secret. Shown once; Creo stores only a hash.

idstringrequired
namestringnullable
key_prefixstringrequired
planstringrequired
daily_call_limitintegerrequired
max_positionsintegerrequired
created_atdatetimerequired