Authenticating With The API

When making API requests, it is crucial to authenticate them to ensure secure communication and proper authorization. Mezmo’s API utilizes a key-based authentication system. This method involves including a unique access key in the Authorization header of your request, prefixed with the Token scheme.

Quick start

Add the Authorization header - Format: Authorization: Token <your_token>

export $MZM_ACCESS_KEY = 'sta_1a2b3c4d5e6f7890abcdef1234567890abcdef12'

curl -H "Authorization: Token $MZM_ACCESS_KEY" \
     -H "Accept: application/json" \
     https://api.mezmo.com/v3/pipeline

const res = await fetch('https://api.mezmo.com/v3/auth/token>', {
	headers: {
		'Authorization': `Token ${process.env.MZM_ACCESS_KEY}`,
		'Accept': 'application/json'
	}
})

For enterprise operations, additional, specific account context may be included for delegation as needed.

1. x-delegate-account-id: <account_id> (enterprise tokens only)

export MZM_ENTERPRISE_KEY = 'ste_d710b57dc7dedde45ccc4c35b68cf385b89f8dc3'

curl -H "Authorization: Token $MZM_ENTERPRISE_KEY" \
     -H "x-delegate-account-id: 507f1f77bc" \
     https://api.mezmo.com/v3/pipeline

---

Key Considerations

Choose the Appropriate Access Key Type:

Mezmo offers different token types, each designed for specific use cases and levels of access. Carefully select the token type that best aligns with the requirements of your application or integration. This might include:

1. Service Accounts: Often used for machine-to-machine communication, background services, or applications that require persistent access. Service accounts have only single access key associated with it.

   1. Enterprise Service Accounts: Similar to a standard service account with the exception that these access keys are not bound to an individual account and may be used to manage an enterprise programmatically, or interface with any of the child accounts associated with an enterprise organization.

2. Personal Access Keys: Associated with a specific user with in the organization which may have a shorter lifespan. These keys inherently have the level of access as the user it is associated with. Changing the permissions granted to a user changes the scope of any access keys they may have provisioned.

   1. Scoped Access: Additionally, personal access keys may be created with a limited level of access to further restrict what they may be used for.

Examples

export MZM_ACCESS_KEY = 'sta_34b8f6897cd3396e6af781c3bfe34065b690f90b'
export MZM_ENTERPRISE_KEY = 'ste_d710b57dc7dedde45ccc4c35b68cf385b89f8dc3'
# Account‑scoped
curl -H "Authorization: Token $MZM_ACCESS_KEY" \
     https://api.mezmo.com/v3/pipeline
     
# Enterprise‑scoped
curl -H "Authorization: Token $MZM_ENTERPRISE_KEY" \
     https://api.mezmo.com/v3/enterprise/account

# Delegation (enterprise keys  only)
curl -H "Authorization: Token $MZM_ENTERPRISE_KEY" \
     -H "x-delegate-account-id: 507f1f77bc" \
     https://api.mezmo.com/v3/pipeline

Security best practices

• Rotate tokens regularly. Use expirations and rotate before they expire.
• Grant only what you need. Prefer minimal scopes.
• Use service accounts for automation. Avoid personal tokens in CI/CD.
• Store tokens in environment variables or a secret manager. Do not hard‑code tokens.
• Implement a mechanism to quickly revoke tokens if they are suspected of being compromised or are no longer needed.

# Good
export MZM_ACCESS_KEY="sta_34b8f6897cd3396e6af781c3bfe34065b690f90b"
curl -H "Authorization: Token $MZM_ACCESS_KEY" https://api.mezmo.com/v3/pipeline

# Avoid
curl -H "Authorization: Token sta_34b8f6897cd3396e6af781c3bfe34065b690f90b" \ 
     https://api.mezmo.com/v3/pipeline

---

Troubleshooting

Common HTTP codes

Code	Meaning	What to do
401	Token invalid or expired	Check token format and expiration. Re‑issue if needed.
403	Insufficient permissions	Verify the token has the required scopes.
404	Resource not found	Check the endpoint URL and resource IDs.

Quick validation

Expect 200 (valid) or 401 (invalid)

export MZM_ACCESS_KEY = 'sta_34b8f6897cd3396e6af781c3bfe34065b690f90b'
curl -I -H "Authorization: Token $MZM_ACCESS_KEY" https://api.mezmo.com/v3/pipeline

Debug headers

Responses from the API will include additional metadata in the response headers describing what the system understood about the subject making the request. The can be identified with a common prefix - x-auth-*

export MZM_ACCESS_KEY = 'sta_34b8f6897cd3396e6af781c3bfe34065b690f90b'
curl -v -H "Authorization: Token $MZM_ACCESS_KEY" https://api.mezmo.com/v3/pipeline
# Inspect x-auth-* headers in the response

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-request-id: 0e87e821-c93c-4642-a69c-8ac40478239e
x-auth-subject-id: 507f1f77bcf86cd799439015
x-auth-account-id: 507f1f77bcf86cd799439012
x-auth-enterprise-id: 68c584136b9b08b8fc53a85e
x-auth-subject-email: [e-mail]
x-auth-account-short-id: d3396ea1f
x-auth-access-type: access