Skip to main content
Most Tyms Developer API routes use a business API key in a header. You pass a secret, and the server enforces which business (or partner program) the credential belongs to. Building an integration app for many Tyms customers? Use OAuth 2.0 instead of asking each user for their business secret key.

​
Production vs sandbox

Credentials are environment-specific. Production keys from the Tyms app authenticate against https://api.usetyms.com/v1/adam; sandbox keys authenticate against https://staging-api.usetyms.com/v1/adam. See Environments for the full table. To test integrations before production, email developer@usetyms.com for sandbox account setup. Tyms provisions staging businesses and issues keys that match the sandbox host.

​
Two kinds of credentials

​
Business secret key (tyms_sk_...)

Used for every v1/adam route except partner distributor routes and OAuth steps that document their own auth.
  • Issued per business from the Tyms app (Settings → Business settings → API).
  • Grants access only to that business’s data.
  • Public key (tyms_pk_...) is not used as the Bearer-style secret for these REST calls; integrations use the secret key.

​
Partner API key (adam_partner_sk_... or equivalent)

Used for partner distributor routes under API reference → Partners (full URLs under Environments):
  • POST /register-business
  • GET /referred-businesses
  • GET /referred-businesses/{business_uuid}/billing-status
  • POST /referred-businesses/{business_uuid}/add-seats
  • POST /referred-businesses/{business_uuid}/add-credits
  • Issued when Tyms onboards you as a referral business partner (distributor).
  • Creates a new business and optionally returns that business’s Developer API keys when grant_access is admin.
  • Seat and credit grants debit your partner credit holding (see Partners).
  • After registration, use the returned tyms_sk_... for that customer’s day-to-day bookkeeping API calls — not the partner key.
Partner program onboarding (admin registration, contract terms, commission or prepaid structures) is handled outside this reference. If you are integrating as a partner, complete Tyms’s partner onboarding first so you receive partner credentials. Start with the Partners guide and API reference → Partners.

​
Accepted header names

Send the key in any one of these headers (same value):
  • X-API-Key
  • api-key
  • sk

​
Developer API subscription

On protected routes, the business must meet Tyms’s Developer API subscription rules. If not, the API responds with 403 Forbidden and an explanatory message.

​
Validate a business key

To confirm a key and load business metadata, call GET /auth/validate. Request/response fields are documented on Validate business.

​
Security practices

  • Store tyms_sk_... and partner secrets in a secret manager or environment variables — never in client-side code or public repos.
  • Rotate keys from the Tyms app if a secret is exposed.
  • Prefer TLS only (https://api.usetyms.com or https://staging-api.usetyms.com for sandbox).
  • OAuth 2.0 — third-party integration apps connecting Tyms users
  • API overview — errors, rate limits, UUID rules
  • Partners — onboarding, billing models, and distributor routes