Manage Signed from your own code

Getting started

1. 1

   Create a key

   In the portal, open API keys and choose Create key. Give it a name and only the scopes it needs.

2. 2

   Copy the secret

   It is shown once. Only a hash is stored, so it cannot be read back. If you lose it, rotate the key instead.

3. 3

   Send it in a header

   Every request carries X-API-Key. Keys are not cookies, so nothing is shared between tabs or browsers.

Keys are created in the Signed portal. You can also manage them here, through the API keys endpoints, once you have one.

Authentication

Send your key in the X-API-Key header. A Bearer token that looks like a Signed key works too. Every key belongs to one organisation, so there is no organisation to pass in.

curl "https://api.usesigned.co.uk/api/v1/users?limit=5" \
  -H "X-API-Key: $SIGNED_API_KEY"

Keys are hashed before they are stored, so a key can never be read back from the database or shown in the portal again. Revoke a key the moment it is no longer needed.

Scopes

Each key carries a set of scopes. An endpoint that needs a scope the key does not hold returns 403 with a scope property naming what was missing. Give each integration the smallest set that works, and use * only for a trusted, server-side integration.

Errors

Failures come back as JSON with an error message you can show to a person, and a reason code you can branch on.

{
  "error": "This key can read people but not change them.",
  "reason": "insufficient_scope",
  "scope": "users:write"
}

Machine-readable specification

The whole API is described by an OpenAPI 3.1 document. Point a client generator, Postman or Insomnia at it, or read it straight from the API.

curl "https://api.usesigned.co.uk/api/v1/openapi.json"

Endpoints

Grouped by what they act on. Every endpoint has a documentation tab and a Try it tab that runs against the live API with the key you saved at the top of the page.

• Overview2 endpointsThe API index and the machine-readable OpenAPI specification. Neither needs a key.Read the reference
• Organisation5 endpointsYour organisation’s details, the company defaults used in signatures, and usage counts.Read the reference
• Signature templates8 endpointsCreate, edit and assign the signature templates your organisation uses.Read the reference
• People7 endpointsYour directory. Create, update and import the people signatures are built for.Read the reference
• Departments4 endpointsThe department tree, used to scope rules and campaigns.Read the reference
• Assignment rules4 endpointsDecide which template applies to which people, by department, domain or person.Read the reference
• Campaigns4 endpointsDated banners appended under signatures, for promotions and notices.Read the reference
• Signature delivery2 endpointsLook up the signature for an email address, or stamp it into an outgoing message.Read the reference
• Audit log1 endpointA paged, read-only history of everything that has changed in the organisation.Read the reference
• API keys7 endpointsManage the keys themselves: create, limit, rotate and revoke.Read the reference