Bulk Entitlements Upload API (Early Access)

BalkanID Entitlements Upload CSV Format

In this section, we will explain the BalkanID Entitlements CSV format.

Sample CSV

Project	Privilege Name*	Privilege Value*	Email	User ID	Username	Name	Connection	Connection Type	Resource	Resource Type
balkanid	pull	true	ayden@example.com	01234567	koch71	Ayden Koch	read	respository-role	ops	repository
balkanid	push	false	ayden@example.com	01234567	koch71	Ayden Koch	read	respository-role	ops	repository
balkanid	admin	false	ayden@example.com	01234567	koch71	Ayden Koch	read	respository-role	ops	repository
balkanid	pull	true	ayden@example.com	01234567	koch71	Ayden Koch	admin	respository-role	ops	repository
balkanid	push	true	ayden@example.com	01234567	koch71	Ayden Koch	admin	respository-role	ops	repository
balkanid	admin	true	ayden@example.com	01234567	koch71	Ayden Koch	admin	respository-role	ops	repository

NOTE: Columns with * are required always.

NOTE: In this sample we are using Github example for familiarity. Please note that BalkanID offers a direct Github integration.

Column Definitions

Column Name	Column Description
Project	Optional - This is a “project”-level of organization in your application. This can be a Github organization, Slack organization, AWS account number, Azure directory, Google domain, Okta Site URL, etc. In the sample CSV, this is a Github organization “balkanid”. While optional, it is recommended that you provide Project value. If not provided, the Project value is set to “default”.
Privilege Name	Required - The name of the action/permission/entitlement. These are typically actions that can be taken on a resource. In the sample CSV, these are “pull”, “push”, and “admin”, which are actions associated with a repository.
Privilege Value	Required - In many cases, these will be “true”. In some cases, it is useful to model an explicit deny by including entitlements where Privilege Value is “false”. In the sample CSV, we see both “true” and “false” privilege values.
Email	One of Email, User ID, or Username required - The email associated with the identity to which this entitlement belongs to, if available. In the sample CSV, this is “ayden@example.com”.
User ID	One of Email, User ID, or Username required - Some applications have an ID that is separate from email or username. This is the place to include that ID.
Username	One of Email, User ID, or Username required - The username associated with the identity to which this entitlement belongs to. In the sample CSV, this is “koch71”.
Name	Optional - The name of the identity to which this entitlement belongs to, if available. This can be the name of a person, a service account, or other names.
Connection	Optional, required if Connection Type is present - Connection describes how the identity (identified by the Username) gains the privilege (identified by Privilege Name and Privilege Value) to the resource (identified by Resource and Resource Type). In the sample CSV, the connection is the repository role granted to the identity: “read” and “admin”.
Connection Type	Optional, required if Connection is present - Connection Type describes the type of the Connection. Typical connection types are “role”, “policy”, “group”, but can include others depending on your application authorization structure. In the sample CSV, this is “repository-role”.
Connection Provider	Optional - The provider of the Connection, used to represent a multilevel connection. If this is present, Connection and Connection Type must also be present.
Connection Provider Type	Optional - The type of the Connection Provider, If this is present, Connection Provider, Connection and Connection Type must not be empty.
Resource	Optional, required if Resource Type is present - The resource this entitlement references. In the sample CSV, the resource is the “ops” repository.
Resource Type	Optional, required if Resource is present - A useful resource type that groups resources in your application. This can be a Github repository/organization/application, AWS service, a Slack channel, etc. In the sample CSV, the resource type is “repository”.
Project Aliases	Optional - This is a comma-separated list of aliases for the Project. This is useful when you have multiple names for the same Project.

Required Columns

Privilege Name and Privilege Value are always required.

One of Email, User ID, or Username are required. You may provide one, two, or all three of Email, User ID, or Username.

If you provide Connection or Connection Type column, the other one Connection Type or Connection is required.
If Connection Provider and Connection Provider Type is present, then Connection and Connection Type column is required.
If you provide Resource or Resource Type column, the other one Resource Type or Resource is required.

All other columns are optional.

Restrictions

When Email, User ID, and Username are provided together, instead of only one of them, they always have to correspond to the same triplet.

For example, the following is valid because the triplet of Email, User ID, and Username is the same in both rows:

Email	User ID	Username
ayden@example.com	01234567	koch71
ayden@example.com	01234567	koch71

However, the following is not valid and will result in an error, because the same Email and User ID have two different Usernames associated with them:

Email	User ID	Username
ayden@example.com	01235467	koch71
ayden@example.com	01235467	ayden71

Similarly, the following is not valid and will result in an error, because the Username and User ID have two different Emails associated with them:

Email	User ID	Username
ayden@example.com	01235467	koch71
ayden.koch@example.com	01235467	koch71

Similarly, the following is not valid and will result in an error because the Username and Email have two different User IDs associated with them:

Email	User ID	Username
ayden@example.com	01235467	koch71
ayden@example.com	98765432	koch71

In summary, you only need to provide one of: Email, User ID, Username. If you provide more than one, the combination of Email, User ID, and or Username must be the same on every row they appear on.

Upload the CSV file via the pre-signed URL

After retrieving the pre-signed URL in the previous step, all that remains is to upload the CSV in BalkanID Canonical CSV format to the pre-signed URL.
Below is a summary of the request using curl:

The request URL is the pre-signed URL from previous step.

The request method is PUT.

Required request body is the CSV in BalkanID Entitlements CSV format.

application/json

upload url response

Body

Upload URL endpoint response

url

string

required

The value is the pre-signed URL to which to upload your CSV file.

Example

{
    "url": "string"
}

Bulk Entitlements Upload API (Early Access)

BalkanID Entitlements Upload CSV Format

Sample CSV

Column Definitions

Required Columns

Restrictions

Upload the CSV file via the pre-signed URL

Request

Request samples

Responses

Bulk Entitlements Upload API (Early Access)

BalkanID Entitlements Upload CSV Format#

Sample CSV#

Column Definitions#

Required Columns#

Restrictions#

Upload the CSV file via the pre-signed URL#

Request

Request samples

Responses

BalkanID Entitlements Upload CSV Format

Sample CSV

Column Definitions

Required Columns

Restrictions

Upload the CSV file via the pre-signed URL