conductorone-api

Summary

ConductorOne API: The ConductorOne API is a HTTP API for managing ConductorOne resources.

Table of Contents

• SDK Installation
• SDK Example Usage
• Available Resources and Operations
• Retries
• Error Handling
• Server Selection
• Custom HTTP Client
• Authentication
• Special Types

SDK Installation

To add the SDK as a dependency to your project:

go get github.com/ConductorOne/conductorone-sdk-go

SDK Example Usage

Example

package main

import (
	"context"
	conductoronesdkgo "github.com/conductorone/conductorone-sdk-go/v2"
	"github.com/conductorone/conductorone-sdk-go/v2/pkg/models/shared"
	"log"
)

func main() {
	ctx := context.Background()

	s := NewWithCredentials(ctx, &ClientCredentials{
		ClientID:     "",
		ClientSecret: "",
	} )

	res, err := s.Apps.Create(ctx, &shared.CreateAppRequest{
		Owners: []string{
			"string",
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	if res.CreateAppResponse != nil {
		// handle response
	}
}

Available Resources and Operations

Available methods

AppAccessRequestsDefaults

• CancelAppAccessRequestsDefaults - Cancel App Access Requests Defaults
• CreateAppAccessRequestsDefaults - Create App Access Requests Defaults
• GetAppAccessRequestsDefaults - Get App Access Requests Defaults

AppEntitlementOwners

• Add - Add
• List - List
• Remove - Remove
• Set - Set

AppEntitlements

• Create - Create
• Delete - Delete
• Get - Get
• List - List
• ListForAppResource - List For App Resource
• ListForAppUser - List For App User
• ListUsers - List Users ⚠️ Deprecated
• Update - Update

AppEntitlementSearch

• Search - Search
• SearchAppEntitlementsForAppUser - Search App Entitlements For App User
• SearchAppEntitlementsWithExpired - Search App Entitlements With Expired

AppEntitlementUserBinding

• ListAppUsersForIdentityWithGrant - List App Users For Identity With Grant
• SearchGrantFeed - Search Grant Feed
• SearchPastGrants - Search Past Grants

AppOwners

• Add - Add
• List - List
• Remove - Remove
• Set - Set

AppReport

• List - List

AppReportAction

• GenerateReport - Generate Report

AppResource

• CreateManuallyManagedAppResource - Create Manually Managed App Resource
• DeleteManuallyManagedAppResource - Delete Manually Managed App Resource
• Get - Get
• List - List
• Update - Update

AppResourceOwners

• List - List

AppResourceSearch

• SearchAppResourceTypes - Search App Resource Types

AppResourceType

• CreateManuallyManagedResourceType - Create Manually Managed Resource Type
• DeleteManuallyManagedResourceType - Delete Manually Managed Resource Type
• Get - Get
• List - List
• UpdateManuallyManagedResourceType - Update Manually Managed Resource Type

Apps

• Create - Create
• Delete - Delete
• Get - Get
• List - List
• Update - Update

AppSearch

• Search - Search

AppUsageControls

• Get - Get
• Update - Update

AppUser

• Update - Update

Attributes

• CreateAttributeValue - Create Attribute Value
• DeleteAttributeValue - Delete Attribute Value
• GetAttributeValue - Get Attribute Value
• ListAttributeTypes - List Attribute Types
• ListAttributeValues - List Attribute Values

AttributeSearch

• SearchAttributeValues - Search Attribute Values

Auth

• Introspect - Introspect

AWSExternalIDSettings

• Get - Get

Connector

• Create - Create
• CreateDelegated - Create Delegated
• Delete - Delete
• ForceSync - Force Sync
• Get - Get
• GetCredentials - Get Credentials
• List - List
• RevokeCredential - Revoke Credential
• RotateCredential - Rotate Credential
• Update - Update
• UpdateDelegated - Update Delegated

Directory

• Create - Create
• Delete - Delete
• Get - Get
• List - List

Export

• Create - Create
• Delete - Delete
• Get - Get
• List - List
• ListEvents - List Events
• Update - Update

ExportsSearch

• Search - Search

PersonalClient

• Create - Create
• Delete - Delete
• Get - Get
• List - NOTE: Only shows personal clients for the current user.
• Update - Update

PersonalClientSearch

• Search - NOTE: Searches personal clients for all users

Policies

• Create - Create
• Delete - Delete
• Get - Get
• List - List
• Update - Update

PolicySearch

• Search - Search

PolicyValidate

• ValidateCEL - Validate Cel

RequestCatalogManagement

• AddAccessEntitlements - Add Access Entitlements
• AddAppEntitlements - Add App Entitlements
• Create - Create
• Delete - Delete
• ForceRunBundleAutomation - Force Run Bundle Automation
• Get - Get
• GetBundleAutomation - Get Bundle Automation
• List - List
• ListEntitlementsForAccess - List Entitlements For Access
• ListEntitlementsPerCatalog - List Entitlements Per Catalog
• RemoveAccessEntitlements - Remove Access Entitlements
• RemoveAppEntitlements - Remove App Entitlements
• SetBundleAutomation - Set Bundle Automation
• Update - Update

RequestCatalogSearch

• SearchEntitlements - Search Entitlements

Roles

• Get - Get
• List - List
• Update - Update

SessionSettings

• Get - Get
• Update - Update

SystemLog

• ListEvents - List Events

Task

• CreateGrantTask - Create Grant Task
• CreateOffboardingTask - Create Offboarding Task
• CreateRevokeTask - Create Revoke Task
• Get - Get

TaskActions

• Approve - Approve
• Comment - Comment
• Deny - Deny
• EscalateToEmergencyAccess - Escalate To Emergency Access
• HardReset - Hard Reset
• Reassign - Reassign
• Restart - Restart

TaskSearch

• Search - Search

User

• Get - Get
• List - List

UserSearch

• Search - Search

Webhooks

• Create - Create
• Delete - Delete
• Get - Get
• List - List
• Test - Test
• Update - Update

WebhooksSearch

• Search - Search

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or an error, they will never return both. When specified by the OpenAPI spec document, the SDK will return the appropriate subclass.

Error Object	Status Code	Content Type
sdkerrors.SDKError	400-600	/

Example

package main

import (
	"context"
	"errors"
	conductoronesdkgo "github.com/conductorone/conductorone-sdk-go/v2"
	"github.com/conductorone/conductorone-sdk-go/v2/pkg/models/sdkerrors"
	"github.com/conductorone/conductorone-sdk-go/v2/pkg/models/shared"
	"log"
)

func main() {
	ctx := context.Background()

	s := NewWithCredentials(ctx, &ClientCredentials{
		ClientID:     "",
		ClientSecret: "",
	})
	res, err := s.Apps.Create(ctx, &shared.CreateAppRequest{
		Owners: []string{
			"string",
		},
	})
	if err != nil {

		var e *sdkerrors.SDKError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}
	}
}

SDK Example Usage with Custom Server/Tenant

Example

package main

import (
	"context"
	conductoronesdkgo "github.com/conductorone/conductorone-sdk-go/v2"
	"github.com/conductorone/conductorone-sdk-go/v2/pkg/models/shared"
	"log"
)

func main() {
	ctx := context.Background()

	/* Optional Override 
	* Server URL will be extracted from client, optionally, you can
	* provide a server URL or a tenant domain (will create URL https://{tenant_domain}.conductor.one) 
	*/
	opts := []sdk.CustomSDKOption{}
	opt, _ := sdk.WithTenantCustom("Server URL or Tenant Domain")
	opts = append(opts, opt)

	s := NewWithCredentials(ctx, &ClientCredentials{
		ClientID:     "",
		ClientSecret: "",
	} opts...)

	res, err := s.Apps.Create(ctx, &shared.CreateAppRequest{
		Owners: []string{
			"string",
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	if res.CreateAppResponse != nil {
		// handle response
	}
}

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retry.Config object to the call by using the WithRetries option:

package main

import (
	"context"
	conductoronesdkgo "github.com/conductorone/conductorone-sdk-go"
	"github.com/conductorone/conductorone-sdk-go/pkg/models/shared"
	"github.com/conductorone/conductorone-sdk-go/pkg/retry"
	"log"
	"pkg/models/operations"
)

func main() {
	s := conductoronesdkgo.New(
		conductoronesdkgo.WithSecurity(shared.Security{
			BearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
			Oauth:      "<YOUR_OAUTH_HERE>",
		}),
	)

	ctx := context.Background()
	res, err := s.Apps.Create(ctx, nil, operations.WithRetries(
		retry.Config{
			Strategy: "backoff",
			Backoff: &retry.BackoffStrategy{
				InitialInterval: 1,
				MaxInterval:     50,
				Exponent:        1.1,
				MaxElapsedTime:  100,
			},
			RetryConnectionErrors: false,
		}))
	if err != nil {
		log.Fatal(err)
	}
	if res.CreateAppResponse != nil {
		// handle response
	}
}

If you'd like to override the default retry strategy for all operations that support retries, you can use the WithRetryConfig option at SDK initialization:

package main

import (
	"context"
	conductoronesdkgo "github.com/conductorone/conductorone-sdk-go"
	"github.com/conductorone/conductorone-sdk-go/pkg/models/shared"
	"github.com/conductorone/conductorone-sdk-go/pkg/retry"
	"log"
)

func main() {
	s := conductoronesdkgo.New(
		conductoronesdkgo.WithRetryConfig(
			retry.Config{
				Strategy: "backoff",
				Backoff: &retry.BackoffStrategy{
					InitialInterval: 1,
					MaxInterval:     50,
					Exponent:        1.1,
					MaxElapsedTime:  100,
				},
				RetryConnectionErrors: false,
			}),
		conductoronesdkgo.WithSecurity(shared.Security{
			BearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
			Oauth:      "<YOUR_OAUTH_HERE>",
		}),
	)

	ctx := context.Background()
	res, err := s.Apps.Create(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	if res.CreateAppResponse != nil {
		// handle response
	}
}

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Feel free to open a PR or a Github issue as a proof of concept and we'll do our best to include it in a future release !

SDK Created by Speakeasy