SOP: API Access Request

📋 This SOP outlines the required steps Customer Support must follow when a customer requests access to the Sitemetric API.

API accounts differ from user accounts in that API access is provided as a single account per customer, rather than being created on a per-user basis.

🔄 Step-by-Step Procedure

1️⃣ Customer Support Receives a Request

Receive the request via email, ticket, or customer message.

⚠️ Ensure a proper support ticket is created and contains: - Customer name - Project name - Names/emails of individuals requesting access - Summary of the request All following steps must be documented in this ticket.

2️⃣ Obtain Approval from the User Account Approver

Identify the designated User Account Approver for the project using the 🗃️ Customer App User Account Approvers Matrix.
Send an approval request including the names/emails of users requesting API access.
Wait for written confirmation before continuing.

3️⃣ Create API Credentials

Once approval is received, create the API credentials following the process outlined in the Internal Reference: Creating API Credentials section below.

You will need superadmin access to create API credentials. See the detailed steps in the Internal Reference section below.

4️⃣ Send Approved API Information to the Customer

Send to customer once: - Project approver has confirmed access, and - You have created the credentials and uploaded them to Sitemetric Vault

Use the template below ↓

🔧 Internal Reference: Creating API Credentials

The following steps are performed by authorized superadmin users.

Internal docs (Auth): https://us.sitemetric.com/docs.html#auth

To give a customer access to our APIs, you'll need to create API credentials for them. They must use these credentials to authenticate and get a Bearer token, which they'll then use to access the API.

We do not support simple api_key access—authentication and token-based access are required.

Create an API Account

You can create API credentials using the app if the user has the "superadmin" role.

Navigate to Admin → Integrations → Sitemetric Api Accounts

The list displays existing accounts. Select an entry to view details and make edits.

⚠️ Important: Do not create multiple API accounts for the same customer. Check the existing accounts list first and reuse the same account for all users from that customer.

ℹ️ Once an API account is created for a customer, the same credentials are used even if more people need access. A Sitemetric Admin typically only needs to intervene again if the Vault share link expires, and a new share link and password need to be provided.

Click the plus icon to open the create dialog:

We recommend including the customer name followed by "API Access" in the Display Name.

Setting Permissions

The most important aspect of creating an account is setting the appropriate permissions. When in doubt, choose a more restrictive configuration.

Sites — If access is meant for a single site, select only that site. If the goal is to give access to all a customer's sites, leave the site field empty and choose Customers instead.
- In some cases, like when a customer is part of a joint venture, it might be necessary to add additional sites or customers.
Scope — Primarily used when giving access to an owner (the company that is paying the customer). Any sites attributed to the owner will be included in the access, so if you choose an owner, leave Sites and Customers empty.
Tenant — Specify which customer is associated with the account. When populated, this makes the customer's custom fields accessible.

Adding Features (Special Cases)

By default, accounts only have the 'api' feature. To access endpoints that require additional permissions (feature flags), edit the account and select those features.

Obtain the Client Credentials

After creating the account, find it in the list and select it. The Account Details view displays two key attributes:

OAuth Client Id
OAuth Client Secret

Copy these two values for the next step.

Reference: Auth Service Documentation

Send Credentials to Customer

Login to Sitemetric Vault
Navigate to the API Credentials folder
Add a new .txt file with contents like the following:

Your login credentials: ``jsx client_id: "< >" client_secret: "< >"` **To get a token, format a POST request to:** [https://us.sitemetric.com/auth/token](https://us.sitemetric.com/auth/token) POST /auth/token is an XHR endpoint which requires the following parameters in the body of an application/x-www-form-urlencoded POST request: - grant_type — This should be client_credentials - scope — This should be api - client_id — The oauth_client_id from the client metadata - client_secret` — The oauth_client_secret from the client metadata For reference: Authentication Documentation

Create a public sharing link (go to Sharing > Public Links) that is:
- Password-protected
- Set to expire in a reasonable amount of time (24 hours, a few days, etc.)
Send the link to the customer, along with the password to access the file in the vault

❓ Common Customer Questions (Docs & Security)

Use these snippets when customers ask about documentation, authentication, and encryption/security.

Where can I find the API documentation?

Share our REST API docs: https://us.sitemetric.com/docs.html

How do we authenticate?

Customers must use OAuth client credentials to obtain a Bearer token, then use that token to call API endpoints.
Share the auth section: https://us.sitemetric.com/docs.html#auth

Troubleshooting: 401 Unauthorized on worker zones endpoint

If a customer receives a 401 when calling /api/v4/workers/ /zones, the API account may be missing a required feature flag.
Ensure the API account includes the worker-zone-access feature (this flag can be added in the Admin UI)

Do you encrypt API responses?

We do not encrypt API response payloads themselves.
Access is controlled by authentication: only an authorized caller that can obtain a token can retrieve data.

What should Support do if asked for “encryption methods used to secure data transmitted”?

Point customers to the auth flow above and explain that API access requires a valid token.
If a customer needs deeper security details beyond what’s covered in the docs, escalate internally (Engineering/Security) rather than speculating.

📧 Customer Response Template

, The following link is to a secured file that contains your credentials: Access to this file will expire in 24 hours. Please use the following password to unlock the file: To get a token, you'll format a POST to: https://us.sitemetric.com/auth/token POST /auth/token is an XHR endpoint which requires the following parameters to be in the body of an application/x-www-form-urlencoded POST request: - grant_type: This should be client_credentials. - scope: This should be api. - client_id: The oauth_client_id from the client metadata. - client_secret: The oauth_client_secret from the client metadata. For reference, you can read about how to obtain a token here: https://us.sitemetric.com/docs.html#auth