Go SDK
Start using the Go SDK​
Learn how to use the Golang SDK in this guide. The Go SDK has some pre-built code examples you can use to learn how to build tools that can interact with IdentityNow (IDN).
You can find the SDK and its examples in its GitHub repo here.
The Go SDK includes the following functionality:
APIs:
The following V2 APIs are available:
Collection Endpoint Workgroups GET Workgroup, PATCH Workgroup, DELETE Workgroup, GET Workgroups, POST Workgroups, GET Workgroup Members, POST Workgroup Members, GET Workgroup Connections, POST Bulk Delete Workgroups Organizations GET Organization, PATCH Organization The following CC APIs are available:
Collection Endpoint Accounts GET Accounts, POST Remove Account Applications GET Applications, GET Application, POST Application, POST Update Application, POST Delete Application, GET Application Access Profiles Connectors GET Connectors, POST Connector, POST Delete Connector, GET Export Connector, POST Import Connector User POST Update User Permissions Sources POST Account Aggregation, GET Export Account Feed System POST Refresh Identities
Search: You can use IDN's search. To learn more about IDN's search, refer to Search.
Transforms: You can use transforms, configurable JSON objects that define easy ways to manipulate attribute data without your needing to write any code. To learn more about IDN's transforms, refer to Transforms.
Pagination: You can use the SDK's pre-built pagination functionality to paginate the responses to your SDK requests. To learn more about pagination, refer to Paginating Results.
Requirements​
You need the following to use the Go SDK:
Golang version 1.18 or above. You can download it here. You can use
go version
to check your version.Your tenant name in IDN. To learn how to find it, refer to Getting Started. The SDK will use this tenant name to connect to your IDN instance.
A PAT with a client secret and ID. To learn how to create one in IDN, refer to Personal Access Tokens. The SDK will use this PAT to authenticate with the SailPoint APIs.
Setup​
To set up your Go SDK, follow these steps:
Create a Go module for the SDK​
Use the go mod init github.com/github-repo-name/projectname
command to create your project. This command creates a "go.mod" file in your project. This "go.mod" file defines your Go module's properties, including its dependencies on other modules and on versions of Go. The "go.mod" file will list your Go module's module path and your current version of Go.
Create a Go application for the SDK​
Create an "sdk.go" file in your project and copy this code example into the file to get started:
package main
import (
"context"`
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
resp, r, err := apiClient.V3.AccountsApi.ListAccounts(ctx).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `AccountsApi.ListAccount``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `ListAccounts`: []Account
fmt.Fprintf(os.Stdout, "First response from `AccountsApi.ListAccount`: %v\n", resp[0].Name)
}
You'll be able to use this code example to run the application. The application will call the Accounts List V3 API endpoint to get the accounts in your tenant and return the first account it finds.
Your project should now have both a "go.mod" file and an "sdk.go" file.
Configure the SDK​
To configure the SDK, create a configuration file or save your configuration as environment variables. You can use any of the following ways to do so:
Manual configuration​
One way to create a configuration file is to create a "config.yaml" file in your project and specify the following information in it:
activeenvironment: example # the key that identifies the currently active environment
authtype: pat # currently only pat and pipeline are supported if the ENV VAR SAIL_AUTH_TYPE is configured to "pipeline" it will override this value
customexporttemplatespath: "" # the path to the users custom export templates file if one is provided
customsearchtemplatespath: "" # the path to the users custom search templates file if one is provided
debug: false # the debug setting
environments: # the configured environments
example:
baseurl: https://example.api.identitynow.com
pat:
accesstoken: example-access-token
clientid: example-client-id
clientsecret: example-client-secret
expiry: example-access-token-expiry
tenanturl: https://example.identitynow.com
You must specify the following information:
activeenvironment
: This key identifies the current active environment the SDK is connecting to. This environment name refers to your IDN tenant name. In the example, the key is "example". You must also make sure the environment name listed underenvironments
matches theactiveenvironment
.authtype
: The authentication type. Currently only "pat" and "pipeline" are supported. Configuring ENV VAR SAIL_AUTH_TYPE to "pipeline" overrides this value. In the example, the authentication type is "pat". You must also make sure the authentication type listed under the environment name "example" matches theauthtype
.baseurl
andtenanturl
: These refer to your IDN tenant URL.clientsecret
: The PAT's client secret.clientid
: The PAT's client ID.
Here's an example:
activeenvironment: devrel # the key that identifies the currently active environment
authtype: pat # currently only pat and pipeline are supported if the ENV VAR SAIL_AUTH_TYPE is configured to "pipeline" it will override this value
customexporttemplatespath: "" # the path to the users custom export templates file if one is provided
customsearchtemplatespath: "" # the path to the users custom search templates file if one is provided
debug: false # the debug setting
environments: # the configured environments
example:
baseurl: https://devrel.api.identitynow.com
pat:
accesstoken: example-access-token
clientid: g0567b766b413b22c05c66e75d532f1b
clientsecret: cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7
expiry: example-access-token-expiry
tenanturl: https://devrel.identitynow.com
You can also specify this optional information:
customexporttemplatespath
: Specifies the folder path to save your custom export templates file in.customsearchtemplatespath
: Specifies the folder path to save your custom search templates file in.debug
: The debug setting. By default, it's set to "false".accesstoken
: The PAT's name.expiry
: The PAT's expiry date.
CLI assisted configuration​
Another way to create a configuration file is to use the SailPoint CLI. To learn how to use the SailPoint CLI to create a configuration file, refer to Assisted Configuration.
Environment variable configuration​
You can also store your configuration in environment variables.
On Linux/Mac, export the following environment variables:
export SAIL_BASE_URL=https://{tenant}.api.identitynow.com
export SAIL_CLIENT_ID={clientID}
export SAIL_CLIENT_SECRET={clientSecret}
To get your environment variables to persist across terminal sessions, add these exports to your shell profile, something like ~/.bash_profile
.
On Windows PowerShell, run the following commands:
$env:SAIL_BASE_URL=https://{tenant}.api.identitynow.com
$env:SAIL_CLIENT_ID={clientID}
$env:SAIL_CLIENT_SECRET={clientSecret}
To get your environment variables to persist across PowerShell sessions, use these commands instead:
[System.Environment]::SetEnvironmentVariable('SAIL_BASE_URL','https://{tenant}.api.identitynow.com')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_ID','{clientID}')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_SECRET','clientSecret}')
Install the SDK​
Install the SDK with the go mod tidy
command. Using go mod tidy
downloads the required dependencies from the source files and updates the "go.mod" file to match those dependencies.
Run an example request​
Once your SDK is installed and configured, you can start accessing the SDK's different functionalities. The SDK includes some prebuilt examples you can copy into your PowerShell instance to start learning how to use the SDK.
Use the examples to learn how to do the following:
Run an example request with the go run sdk.go
command.
Run an API request​
To start using the API, you can copy this example request into your "sdk.go" file:
package main
import (
"context"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
resp, r, err := apiClient.V3.AccountsApi.ListAccounts(ctx).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `AccountsApi.ListAccount``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `ListAccounts`: []Account
fmt.Fprintf(os.Stdout, "First response from `AccountsApi.ListAccount`: %v\n", resp[0].Name)
}
The example API request calls the SailPoint Accounts List V3 API endpoint to get the accounts in your tenant and returns the first account it finds.
In this line, you can make changes to the API you're calling:
resp, r, err := apiClient.V3.AccountsApi.ListAccounts(ctx).Execute()
- To call a different version of the APIs, change
V3
toBeta
,V2
, orCC
. - To call a different API collection, change
AccountsApi
to another collection, likeSourcesApi
, for example. - To call a different endpoint, change
ListAcounts
to another endpoint, likeGetAccountEntitlements
, for example.
You can manipulate the example API request to call different APIs and write different messages for the users.
In this line, you can make changes to the API you're calling:
resp, r, err := apiClient.V3.AccountsApi.ListAccounts(ctx).Execute()
- To call a different version of the APIs, change
V3
toBeta
,V2
, orCC
. - To call a different API collection, change
AccountsApi
to another collection, likeSourcesApi
, for example. - To call a different endpoint, change
ListAcounts
to another endpoint, likeGetAccountEntitlements
, for example.
You can edit the messages produced for successful responses as well as errors in the following lines by editing the messages enclosed in the quotes.
Paginate results​
The SDK has a built-in pagination function you can use to automatically call and collect responses from the APIs that support pagination. Use the syntax shown in this example to call it:
import (
"context"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
// You must import the v3 library so the SDK is aware of the sailpointsdk.Account struct.
sailpointsdk "github.com/sailpoint-oss/golang-sdk/v3"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
// Use the paginate function to get 1000 results instead of hitting the normal 250 limit
resp, r, err := sailpoint.PaginateWithDefaults[sailpointsdk.Account](apiClient.V3.AccountsApi.ListAccounts(ctx))
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `AccountsApi.ListAccount``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `ListAccounts`: []Account
fmt.Fprintf(os.Stdout, "First response from `AccountsApi.ListAccount`: %v\n", resp[0].Name)
}
To find out whether an endpoint supports pagination, refer to its documentation. Any API supporting pagination lists the optional query parameters detailed in Paginating Results.
Search​
To try using the IDN search functionality along with pagination, copy this code into your "sdk.go" file following the main code:
func getSearchResults(ctx context.Context, apiClient *sailpoint.APIClient) {
search := v3.NewSearchWithDefaults()
search.Indices = append(search.Indices, "identities")
searchString := []byte(`
{
"indices": [
"identities"
],
"query": {
"query": "*"
},
"sort": [
"-name"
]
}
`)
search.UnmarshalJSON(searchString)
resp, r, err := sailpoint.PaginateSearchApi(ctx, apiClient, *search, 0, 10, 10000)
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `AccountsApi.ListAccount``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `search`
for i := 0; i < len(resp); i++ {
fmt.Println(resp[i]["name"])
}
}
Use go run sdk.go
to run the search. This example lists all the identities it finds in your tenant.
There are two ways to configure the search:
- You can edit the
searchString
JSON:
searchString := []byte(`
{
"indices": [
"identities"
],
"query": {
"query": "*"
},
"sort": [
"-name"
]
}
`)
In this example, changing the "indices"
from "identities"
to "access profiles"
makes the search return access profiles instead of identities.
- You can edit the string at the end of this
search.Indices
line to do the same thing as a shortcut:
search.Indices = append(search.Indices, "identities")
In this example, the "identities"
string represents an unmarshalled JSON. Changing append(search.Indices, "identities")
to append(search.Indices, "access profiles")
does the same thing editing the searchString
JSON does.
Paginate search results​
The search example includes the syntax you can use to paginate search results. Edit this line to configure the search result pagination:
resp, r, err := sailpoint.PaginateSearchApi(ctx, apiClient, *search, 0, 10, 10000)
The first value refers to the initialOffset
, the starting number for the results, the second refers to the increment
, the number of records per page, and the third refers to the limit
, the last record that can be returned.
For example, changing the first number to 21
, the second to 20
, and the third to 40
would configure the search to return records 21 to 40 and then stop.
Transform​
To start using the SDK to create, manage, and delete transforms, you can copy this example into your "sdk.go" file:
func getTransformResults(ctx context.Context, apiClient *sailpoint.APIClient) {
resp, r, err := apiClient.V3.TransformsApi.ListTransforms(ctx).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `TransformsApi.GetTransformsList``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
b, _ := json.Marshal(resp[0].Attributes)
fmt.Fprintf(os.Stdout, "First response from `TransformsApi.GetTransformsList`: %v\n", string(b))
}
This example calls the List Transforms V3 API endpoint to get the transforms in your tenant and list the results for the first transform it finds, along with the transform inputs and outputs.
Get started​
You can use this SDK to build new tools that extend your IDN platform and improve experiences across your organization. Use this guide to get started, and if you have questions, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!