API authentication

Securing your REST channels

Before securing a channel, create a security definition in Dashboard, and change the password or API key - they are set to random strings by default.

Basic Auth:

API keys:

Each client application gets its own API key. Note that the header for the application to send is always X-API-Key and the value of this key is sent directly in that header.

E.g. in curl it would look like this:

curl -H "X-API-Key: your-api-key" http://localhost:11223/api/v1/services/my-service

Assigning security to a channel

Create or edit a REST channel and select the security definition. Once attached, Zato rejects requests without valid credentials before your service code runs.

If Zato shouldn't handle authentication (e.g. it's not needed or you're implementing a custom auth scheme in your service yourself), you need to explicitly choose "No security definition".

API client groups

You can organize security definitions into groups and assign groups to channels. This is useful when multiple clients need access to the same channel.

How it works:

1. Create security definitions (Basic Auth or API key) for each client
2. Create a group under Security → Groups
3. Drag and drop security definitions as members of the group
4. Assign the group to your REST channel

Any client with credentials from a security definition in the assigned group can access the channel. This lets you:

• Give each client their own credentials
• Revoke access for specific clients without changing the channel
• Track which client made which request via self.channel.security.username

Accessing security info in code

When a request comes in through a secured channel, you can access the authenticated identity:

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class SecuredService(Service):

    name = 'my.secured.service'

    def handle(self):

        # Get the username used for authentication
        username = self.channel.security.username

        # Log who is calling
        self.logger.info(f'Request from: {username}')

        # Use it for authorization decisions
        if username == 'admin':
            self.response.payload = self.get_admin_data()
        else:
            self.response.payload = self.get_user_data()

Test with curl:

# With Basic Auth credentials
curl -u admin:secret123 http://localhost:11223/api/secure/data

# With API key in header
curl -H "X-API-Key: your-api-key" http://localhost:11223/api/secure/data

# Without credentials - returns 401
curl http://localhost:11223/api/secure/data

Custom authentication

For custom authentication schemes such as HMAC signature verification, implement validation in your service code.

Authenticating outgoing calls

Create a Basic Auth, Bearer token or API key definition, remember to set change its password / secret, and assign it to an outgoing connection.

When you make REST calls, Zato will automatically add all the required headers, and it will automatically obtain OAuth2 tokens if you use Bearer tokens.

Basic Auth

Create a Basic Auth definition, then assign it to your outgoing REST connection:

API key

For APIs that require an API key in the X-API-Key header, create an API key security definition and assign it to the connection. Note that the header name must be "X-API-Key".

Bearer token

For APIs that use OAuth 2.0 client credentials flow, create a Bearer token security definition.

Configuration fields:

How it works:

When your service makes an outgoing REST call through a connection with a Bearer token definition attached:

1. Zato checks its internal cache for a valid token
2. If no cached token exists (or it expired), Zato requests a new one from the auth server
3. The token is cached for half its validity period to ensure proactive refresh
4. The Authorization: Bearer <token> header is automatically added to your request

For example, if the auth server returns a token valid for 3600 seconds (1 hour), Zato caches it for 1800 seconds (30 minutes). After 30 minutes, the next API call triggers a fresh token request. This ensures tokens are always refreshed well before expiry.

Scopes at runtime:

You can override scopes per-request using the auth_scopes parameter:

conn = self.out.rest['My API'].conn
response = conn.get(self.cid, auth_scopes='read:users write:users')

If not provided, the scopes from the security definition are used.

Custom authentication

For custom authentication schemes such as SAP HMAC signatures or session-based login/logout flows, pass custom headers directly to the connection.