API Scopes

HCSS controls access to its APIs via scopes. In general, each API will expose at least one read-only scope and one read-and-write scope. When you request an authorization token, you specify the scopes granted to the token as part of the request. When you get API credentials from HCSS, we will configure which scopes you may request. It is recommended to request only the minimum scopes needed for your application. This is a security concept known as the Principal of Least Priviledge.

For example, this HeavyJob GET Access Groups Endpoint uses the heavyjob:read scope. The heavyjob:read scope enables you to view jobs, employees, time cards, and more.

While this HeavyJob POST Create new Cost Code Endpoint uses the heavyjob:write scope. The heavyjob:write scope allows you to perform operations that change data, like creating new materials or code codes.

If you attempt to make an API call lacking the required scopes, you will receive the HTTP 403 Forbidden response. An authorization token expires after an hour, so be sure to double check that you use a non-expired token and possess the correct scopes when Requesting an authorization Token.