Environments and API keys

Organizations, projects, environments, and the keys that belong to them.

Organizations and projects

Everything in coss.com belongs to an organization. Its people are owners, admins or members (see members and roles). An organization has any number of projects, and each project has two environments:

Deleting a project

Owners and admins delete a project from the organization's Settings → Projects page, by typing its slug. It disappears at once: its API keys and OIDC credentials stop working, its scheduled emails, texts and broadcasts never go out, its forms and hosted pages stop answering and its receiving addresses stop taking mail, and its slug is free for a new project. coss.com then deletes everything in its environments in the background: emails, received mail, logs, contacts, suppression lists, webhooks, Hooks, forms, signature requests, bookings, connected calendars and email sub-accounts (also at the email provider). Domains, phone numbers, members and billing belong to the organization and stay, and usage the project already had is still billed. It can't be undone.

API keys

An API key belongs to exactly one environment, and everything it creates or reads lives in that environment. A key can only read emails sent from its own environment.

CI jobs and deployments can do without a stored key: an OIDC credential exchanges their provider's OIDC ID token for a short-lived access token.

Personal keys

A key is either an organization key, for production servers, staging and shared jobs, or a personal key assigned to one member: what a personal key sends counts as that member's spend, so developers can experiment with their own keys and you can see (and cap) what each of them costs.

  • Owners and admins create both kinds, and can assign a personal key to any member.
  • Members create personal keys for themselves in environments an owner or admin has opened to them (the switch on the environment's API keys page). New projects open their development environment and keep production closed; closing an environment leaves existing keys working.
  • coss login and coss init create personal keys of the member who approves them.
  • A personal key works only while its owner is a member: it is revoked when they leave or are removed (also by directory sync), and refused while their account is banned.
  • Organization-wide permissions (managing domains, reading billing and the audit log) work on a personal key only while its owner's role allows them in the dashboard. Everything else in its environment is available to it, so opening an environment gives members write access to it through their keys.

Permissions

When you create a key in the dashboard, you choose what it can do:

Keys with sending access, read-only access or custom permissions are restricted. A restricted key keeps exactly the permissions it was created with: it never gains new ones, even when coss.com adds products. Give each server or job the narrowest key that does its work: an application that only sends email needs only sending access.

A request the key isn't allowed to make fails with 403 permission_error (insufficient_permissions), and the message names the permission it needed. Any key can read its own environment and access with GET /v1/environment (coss.environment.get(): api_key.access and api_key.permissions) and revoke itself. To change what a key can do, create a new key and revoke the old one.

Keys are secrets. Call coss.com from your server, never from a browser: the SDK refuses to run where a document global exists unless you opt in with dangerouslyAllowBrowser.

Creating a live key requires a verified email address on your account.

Sandbox behaviour

Sandbox keys accept any from address and never deliver anything. Delivery events are simulated the way the Amazon SES mailbox simulator behaves, so you can test failure handling:

Every sandbox email also gets email.sent.

Every other product works in a sandbox too, and nothing is billed unless the table says so:

Real mail a sandbox environment receives, at an inbox or any of its addresses, is billed as received email.

Last updated