Generic API Integration (No-Code API Form)

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.

Login to Zilla as admin.
Click Add application in the top right corner.
On the Add Application page search for the application you want to add to Zilla and click Add to Applications if found. Otherwise, add a custom application by going to the Custom Application tab.

Add details for the custom application and click Add to Applications.

Note: Name of the application can never be Generic, GenericOauth, generic, or generic oauth.

4. You will be redirected to the application details page.

5. Click the Gear icon in the top right to the left of Sync now.

6. You will see the configuration dialogue, click Show Alternate Configuration Options.

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 now to 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.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:

{
  pagelen: number,
  size: number
  users: [
          {user1 object},
          {user1 object}
         ]
}

Accounts Property Overrides: This setting maps Zilla fields to the API fields. 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):

{
  "id": "userId",
  "username": "name",
  "firstName": "firstname",
  "lastName": "lastname",
  "status": "enabled",
  "email": "email",
  "roles": "roles",
  "lastLogin": "lastLoggedIn",
  "employeeId": "EID"
}

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. 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’

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

Note: If the Zilla fields and the fields from the API response are the same, then this configuration property can be left blank.

Note: Ensure there are no spaces when entered into the box, else this will raise an error

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:

{
  'name':'john doe',
  'email':john.doe@access-ventures.com',
  'role':{
    'role_name':'User',
    'date_added':'9/22/2024'
  }
}

then to pull the role, you can use the format "roles":"role.role_name" to pull the role affiliated with the account

Optional API No-Code Fields

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, cursor-based and nextUrl based 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 can be limit-offset/cursor-based/nextUrl 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"}.
- In cursor-based pagination, one parameter is returned in the response which specifies the next page cursor. Typically, it is cursor, but this 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 parameter in the response is nextPageCursor then the value here would be {"cursorKey": "nextPageCursor", "cursorPath": "response_metadata.next_cursor", "limit": "limit"}
  - cursorKey: Determines the key of the cursor from the response, e.g., nextPageCursor.
  - cursorPath: Determines the the path to cursor.
  - limit: Determines the limit key in the response.
- In nextUrl based pagination, response can have the nextUrl which is used to get the next set of data. Typically, it is nextUrl, but this may not be the case. If it isn't, then you can use this setting to override thep; default parameter names. For example, if the response contains {data: [], nextUrl: {uri: "", path: ""}}, the value will be {"nextUrlKey": "nextUrl.uri"}. Another possible case would be {data: [], nextUrl: ""} where the value will be {"nextUrlKey": "nextUrl"}.

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}

– To generate your base64 encoded token, you can use an online base64 encoder and input your username and password in this format <username>:<password>

– For Bearer, Token, and JWT Auth, the Value will be Bearer {base64 encoded Token}

9. Click Next/Sync now to start the sync.

Notes:

It is recommended to refer to developer documentation before doing generic sync.
Authorization Url, Token Url, Client Id, Client Secret, and Space separated scopes are optional if the user syncs without oauth. Then the header name and value could be added which are also optional if the API does not support authentication.

Please contact Support@zillasecurity.com for assistance.