Authentication

Every request needs an API key. An administrator of your Matrix TimeCard account creates the key on the API Keys page of the admin site. See Getting started for the steps.

Back to the index

Send the key

Send the key in the X-API-Key header:

GET /api/v1/activities?kind=Job HTTP/1.1
Host: <your-instance-host>
X-API-Key: tc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You can also send it as a bearer token. Use this form when your HTTP client supports only bearer tokens:

Authorization: Bearer tc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rule	Detail
Both headers sent	The API reads `Authorization` and ignores `X-API-Key`.
Key in the URL	Not accepted. URLs are written to logs. Never put the key in a query string.
No key, or a value with no key prefix	`401` with the body `{"status":401,"message":"Unauthorized: no bearer token was sent."}`. This one reply is not a problem body.

Key format

Prefix	Use
`tc_live_`	A key for your live integration
`tc_test_`	A key that your administrator marked as a test key

After the prefix come 43 letters and digits. The API reads a value as a key only when it starts with tc_live_ or tc_test_. Send the whole key, prefix included.

A tc_test_ key writes live data. The prefix is only a label for your own records. A tc_test_ key works the same as a tc_live_ key. There is no sandbox mode. Test against a test account that your administrator sets up.

Scopes

A key can do only what its scopes allow. Your administrator picks the scopes when they create the key. A request that needs a scope that the key does not have gets 403 with code insufficient_scope. The response lists the scopes that the request needs in required_scopes.

Scope	Lets the key
`activity:read`	Read Jobs, Work Orders, Meet Points, their Phase Codes and the reference lists
`activity:write`	Create and update Jobs, Work Orders, Meet Points and their Phase Codes
`geofences:read`	Reserved for boundary reads. Each activity already lists its boundaries in `geofences`.
`geofences:write`	Draw a job-site boundary, redraw one, or turn one off or on
`geofences:publish`	Make a boundary that the key draws live at once. Without it, a drawn boundary waits as a draft for an administrator to publish.
`equipment:read`	Read equipment
`equipment:write`	Create, update, deactivate and reactivate equipment
`reference-changes:write`	Send proposed Jobs, Phase Codes and equipment for an administrator to approve

Each endpoint in the reference names the scope that it needs.

Give each key the fewest scopes that it needs. Use a separate key for each system.

Company access

A key either covers every company in your account or is bound to one company.

Key	On a write	On a read
Bound to one company	Writes only to that company. It can leave `companyCode` out. If it names a different company, it gets `403 forbidden`.	Sees only that company.
Covers every company	Must send `companyCode` on a create when your account has more than one company. If it does not, it gets `400 validation_failed`.	Sees every company. Use the `companyCode` filter to narrow a list.

A companyCode that names no active company that the key can reach gets 404 not_found. A record outside the key's companies gets the same 404 as a record that does not exist.

Source system

Each key that writes has a source system name, for example acme-erp. Your administrator sets it when they create the key.

Every record that the key creates carries this name in sourceSystem.
The key can change only records that its own source system owns. See Conventions: Ownership.
A key that has a write scope but no source system gets 403 forbidden on a write.

Keep the key safe

Matrix TimeCard shows a key one time only. It stores only a hash.
Store the key in a secrets manager or an encrypted setting.
Do not log request headers.
Your administrator can see when each key was last used, and from which address.

Revoke a key

If a key leaks, or a system no longer needs it:

Ask your administrator to open API Keys in the admin site.
The administrator revokes the key. A revoked key stops at once. Requests with it get 401 api_key_revoked.
Create a new key for the system, and put the new key in your secrets manager.

A key that passes its expiry date gets 401 api_key_expired. Create a new key before the old one expires.