Zilla includes a powerful module that can connect to any system that has API endpoints for accounts and permissions. This capability can be leveraged for both internal applications as well as SaaS applications.
What Do I Need to Know About An API to Fill Out the No-Code API Form?
Each API is different, and there are a few questions that need to be answered before filling out our no code form.
The first questions that will need to be answered are:
Does the vender/application have a REST API?
Is there a single endpoint that can be used to pull all the accounts and what their roles/permissions are in the app?
Then, based on this, there are 3 options:
If there is an API, and a single endpoint to pull all accounts and their roles, then you can use the no-code form
If there isn't an API, or the endpoint doesn't exist, then we recommend using ZUS or a CSV import for the app because the SaaS provider doesn't have the infrastructure to pull users
If there is an API, the app isn't an in-house app, and multiple endpoints are needed to pull accounts and their roles, then you can request our engineering team to build you an OOTB integration (can speak with your technical lead or speak to support@zillasecurity.com)
If we can use the No-Code Form, then we recommend researching the following questions:
What is the Base URL and endpoint I will need to use?
How is the API response formatted?
How does the API authenticate? Does it use OAuth, Basic, JWT, Tokens, etc.
If its OAuth, then what are the scopes we need to have authorization to use the users endpoint? Also how do you generate a Secret and Client ID?
If its using Basic/Bearer/JWT/Key auth, how do you generate an API token?
Using The No-Code API Builder
Below are the steps to enable generic integration for applications with the configuration details.
...
7. Enable API Integration, you will see configuration entries to be filled in.
...
...
Enter the configuration based on the details given
...
in the next several sections
Click
Next/Sync nowto start the sync.
Description of No Code Form Details
this section outlines what each field in the no-code form does, and provides context on what each setting is doing.
Required API No-Code Fields
These fields will be filled in every single time we use the form
Frequency: the cadence at which we will sync. See Scheduling an automated sync for more details
...
.
Base URL: Base URL for an application API which we can be found in the developer documentation for the application
...
(Example: For
...
Github, the API base URL is it would be https://
...
api
...
Authorization Header Name 1: Name of the header used to pass the token or API key. Many times this is Authorization. Example: For AHA it would be Authorization. If not required, leave blank.
...
Authorization Header Value 1: The value for the authorization could be API key (Normal or base64 encoded) and the prefix for the API key could be Bearer or Basic followed by space and then API key. Example: For AHA the API key is a normal key with Bearer as a prefix so the header value will be Bearer APIkey. If not required, leave blank.
...
Authorization Header Name 2: Name of the second header. If not required, leave blank.
...
Authorization Header Value 2: The value for the second header. If not required, leave blank.
...
Pagination strategy: Currently Zilla only supports limit-offset pagination for generic integration so the value must be limit-offset.
...
.github.com).
Accounts Endpoint: The endpoint for listing all the users or accounts for an application
...
(Example:
...
users would be the value if the GET request is /users).
Accounts Response Property:
...
This is used when the API response embeds user information into an object array in the response. For example: in the below situation, user objects are embedded in the users section, so the value for the accounts response property config would be .users.
...
This is fairly typical in responses, but the field can be left blank if not applicable:
| Code Block | ||
|---|---|---|
| ||
{
pagelen: number,
size: number
users: [
{user1 object},
{user1 object}
]
} |
Accounts Property Overrides:
...
This setting maps Zilla fields to the API
...
| Code Block |
|---|
{
userId: string,
name: string,
firstname: string,
lastname: string,
enabled: boolean,
roles: string[],
email: string,
lastLoggedIn: Date,
EID: string
.
.
.
so on
} |
So the mapping would befields. It will take on a JSON structure with the Zilla field being the key, and the API field being the value in the JSON (see below example):
| Code Block |
|---|
{
"id": "userId",
"username": "name",
"firstName": "firstname",
"lastName": "lastname",
"status": "enabled",
"email": "email",
"roles": "roles",
"lastLogin": "lastLoggedIn",
"employeeId": "EID"
} |
The left field denotes the Zilla fields and the right one denotes the fields from the API response.
| Info |
|---|
Note: If the Zilla fields and the fields from the API response are the same then this configuration property can be left blank. |
Required Fields
...
Below are Zilla fields that you can map inside of the response:
Required Response Fields
At minimum, you must have the id of a user; however, we highly recommend that you also include this information if it is available:
id: a unique identifier value assigned to an account. Example = 1234. We use this to map the account back to a user in your directory, and also to delineate between accounts. Generally, this will be the email, username, or full name
username: a unique display name assigned to an account . (Example = : jsmith).
email: a unique email addressed assigned to an account . (Example = : jsmith@yourcompany.com).
status: a value that indicates if an account is Active or Inactive. Example = ‘Active’, ‘Inactive’, ‘Enabled’, ‘Disabled’
roles: the permissions associated with an account. Example = ‘Admin’, ‘Default’, ‘Standard’
Account Active Statuses: The status (active or inactive status) response from the API. Value could be true, enabled, active, provisioned, etc. Examples: For AHA we get
trueas active status so the value for this config would betrueand for Okta, we getPROVISIONEDso the value for this config would bePROVISIONED. Values should be comma separated in case of multiple values.
...
Optional Response Fields
lastLogin: When did someone login last
EmployeeID: Another optional way to link accounts back to a user in the directory
firstName: first name of person who owns the account
lastName: last name of person who owns the account
| Info |
|---|
Note: If the Zilla fields and the fields from the API response are the same, then this configuration property can be left blank. |
| Info |
|---|
Note: Ensure there are no spaces when entered into the box, else this will raise an error |
| Info |
|---|
Note: If you have an embedded entry, then you can use a '.' to call the field in this response override. For example, if your JSON response looks like this: |
| Code Block | ||
|---|---|---|
| ||
{
'name':'john doe',
'email':john.doe@access-ventures.com',
'role':{
'role_name':'User',
'date_added':'9/22/2024'
}
} |
| Info |
|---|
then to pull the role, you can use the format |
Optional API No-Code Fields
Pagination
There are situations where an API may only return a select number of accounts at a time. This is referred to as pagination. We support limit-offset pagination right now, which is the most common way this is done, so if there's an app where pagination is happening
Pagination strategy: value must be limit-offset or just leave blank if not applicable.
Pagination Overrides: In limit-offset pagination, two parameters are returned in the response: one that references how many values are returned, and the other being how many accounts have already been returned. Typically, these params are called 'limit' and 'offset', but that may not be the case. If it isn't, then you can use this setting to override our default parameter names. For example, if the parameters in the URL arelimit=50&skip=0 instead of limit=50&offset=0then the value here would be {"limit": "limit", "offset": "skip"}.
Account Status Overrides
Account Active Statuses: there are situations where the active status value isn't marked as Active in an API response. For example, it may be delineated by the value true or PROVISIONED. In these scenarios, you can mark what that active status value is; otherwise, we may mark these accounts as inactive or throw an error
Authentication Fields
There are several fields corresponding to the Authentication mechanisms in an API. For more info on the different types of Authentication types, this guide is a helpful resource. In Zilla, Basic, Bearer, and any other Token-Based authentication will take on a similar configuration in the no-code form. OAuth is going to be different, as the flow is a bit more complex, and more info is needed.
For OAuth
The following fields will need to be filled out for any APIs using OAuth:
Authorization URL: The endpoint for the authorization server, used to get the authorization code. Example: For Okta it is https://{orgdomain}/oauth2/v1/authorize. If you are going for Authorization code based OAuth generic application then you have to specify the authorization URL. Otherwise if your are going for Client Credential Based OAuth in that we can leave it blank.
Token URL: The endpoint for the authentication server. This is used to exchange the authorization code for an access token. Example: For Okta it is https://{orgdomain}/oauth2/v1/token.
Client Id: The client Id issued to the client during the application registration process.
Client Secret: The client secret issued to the client during the application registration process.
Space separated scopes: The scope of the access request. It may have multiple space-delimited values.
...
For example, if you are adding the scopes read-all-users and read-all-groups to your API application, this field would be read-all-users read-all-groups in Zilla.
Redirect URIs:
- If its a authorization code flow kind of OAuth then redirect URI will be https://app.zillasecurity.com/api/auth/callback/genericoauth
- If its a client credential based OAuth then redirect URI will be https://app.zillasecurity.com/api/auth/callback/genericclientcredoauth
for Basic and Token-based Auth
The following fields will need to be filled out for any APIs using Basic, Bearer, Token, or JWT Authentication:
Authorization Header Name 1: This value in this box will always be Authorization
Authorization Header Value 1:
- For Basic auth, the Value will be Basic {base64 encoded token}
- For Bearer, Token, and JWT Auth, the Value will be Bearer {base64 encoded Token}
9. Click Next/Sync now to start the sync.
...