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

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

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: user@example.com

x-auth-account-short-id: d3396ea1f

x-auth-access-type: access