Skip to content
No description, website, or topics provided.
C# JavaScript Other
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Update sdk docs linking to (#191) Jun 8, 2018
openapi Update code with the latest openapi spec (1.11.2) (#339) Aug 16, 2019
tools Upgrade test projects to netcoreapp2.0 (#193) Jun 11, 2018
.gitattributes Base classes and interfaces for new SDK Jun 15, 2017
.gitignore Bump to version 1.0.0-alpha4 (#168) Dec 2, 2017
.travis.yml Upgrades dotnet core version to 2.2 Apr 18, 2019 Update Contributing file and add a Code of Conduct. (#320) May 31, 2019
LICENSE 🐛 Update License Contrib and Third Party Notices Mar 3, 2017 Modifies OktaClient constructor to set a custom JSON Serializer. (#334) Aug 13, 2019
THIRD-PARTY-NOTICES Add third party notices file Jun 22, 2017
build.cake Merges changes into single cake file Sep 10, 2018
build.ps1 Add cake build script Jul 7, 2017 Moving target logic to travis.yml Sep 21, 2018
icon.png Add icon (closes #113) Jul 7, 2017

Support API Reference

Okta .NET management SDK

This repository contains the Okta management SDK for .NET. This SDK can be used in your server-side code to interact with the Okta management API and:

We also publish these other libraries for .NET:

You can learn more on the Okta + .NET page in our documentation.

Release status

This library uses semantic versioning and follows Okta's library version policy.

✔️ The current stable major version series is: 1.x

Version Status
0.3.3 ⚠️ Retiring on 2019-12-11 (migration guide)
1.x ✔️ Stable

The latest release can always be found on the releases page.

Need help?

If you run into problems using the SDK, you can

Getting Started

The SDK is compatible with .NET Standard 1.3 and .NET Framework 4.6.1 or higher.

Install using Nuget Package Manager

  1. Right-click on your project in the Solution Explorer and choose Manage Nuget Packages...
  2. Search for Okta. Install the Okta.Sdk package.

Install using The Package Manager Console

Simply run install-package Okta.Sdk. Done!

The legacy branch is published on NuGet as Okta.Core.Client 0.3.3. This version is retiring and will not be supported past December 11, 2019. It will likely remain working after that date but you should make a plan to migrate to the new 1.x version.

You'll also need:

Construct a client instance by passing it your Okta domain name and API token:

var client = new OktaClient(new OktaClientConfiguration
    OktaDomain = "https://{{yourOktaDomain}}",
    Token = "{{yourApiToken}}"

Hard-coding the Okta domain and API token works for quick tests, but for real projects you should use a more secure way of storing these values (such as environment variables). This library supports a few different configuration sources, covered in the configuration reference section.

Usage guide

These examples will help you understand how to use this library. You can also browse the full API reference documentation.

Once you initialize an OktaClient, you can call methods to make requests to the Okta API.

Authenticate a User

This library should be used with the Okta management API. For authentication, we recommend using an OAuth 2.0 or OpenID Connect library such as Okta ASP.NET middleware.

Get a User

// Get the user with a user ID or login
var vader = await client.Users.GetUserAsync("<Some user ID or login>");

The string argument for GetUserAsync can be the user's ID or the user's login (usually their email).

List all Users

The SDK will automatically paginate Okta collections for you:

// These different styles all perform the same action:
var allUsers = await client.Users.ToArray();
var allUsers = await client.Users.ToList();
var allUsers = await client.Users.ListUsers().ToArray();

Filter or search for Users

var foundUsers = await client.Users
                        .ListUsers(search: $"profile.nickName eq \"Skywalker\"")

Create a User

// Create a user with the specified password
var vader = await client.Users.CreateUserAsync(new CreateUserWithPasswordOptions
    // User profile object
    Profile = new UserProfile
        FirstName = "Anakin",
        LastName = "Skywalker",
        Email = "",
        Login = "",
    Password = "D1sturB1ng!",
    Activate = false,

Activate a User

// With an existing user, call
await vader.ActivateAsync();

Update a User

// Set the nickname in the user's profile
vader.Profile["nickName"] = "Lord Vader";

// Then, save the user
await vader.UpdateAsync();

Get and set custom attributes

You can't create attributes via code right now, but you can get and set their values. To create them you have to use the Profile Editor in the Developer Console web UI. Once you have created them, you can use the code below:

vader.Profile["homeworld"] = "Tattooine";
await vader.UpdateAsync();

Remove a User

// First, deactivate the user
await vader.DeactivateAsync();

// Then delete the user
await vader.DeactivateOrDeleteAsync();

List a User's Groups

// Find the desired user
var user = await client.Users.FirstOrDefault(x => x.Profile.Email == "");

// get the user's groups
var groups = await user.Groups.ToList();

Create a Group

await client.Groups.CreateGroupAsync(new CreateGroupOptions()
    Name = "Stormtroopers",
    Description = "The 501st"

Add a User to a Group

// Find the desired user
var user = await client.Users.FirstOrDefault(x => x.Profile.Email == "");

// find the desired group
var group = await client.Groups.FirstOrDefault(x => x.Profile.Name == "Stormtroopers");

// add the user to the group by using their id's
if (group != null && user != null)
    await client.Groups.AddUserToGroupAsync(group.Id, user.Id);

List a User's enrolled Factors

// Find the desired user
var user = await client.Users.FirstOrDefault(x => x.Profile.Email == "");

// Get user factors
var factors = await user.Factors.ToArray();

Enroll a User in a new Factor

// Find the desired user
var user = await client.Users.FirstOrDefault(x => x.Profile.Email == "");

// Enroll in Okta SMS factor
await user.AddFactorAsync(new AddSmsFactorOptions
    PhoneNumber = "+99999999999",

Activate a Factor

// Find the desired user
var user = await client.Users.First(x => x.Profile.Email == "");

// Find the desired factor
var smsFactor = await user.Factors.First(x => x.FactorType == FactorType.Sms);

// Activate sms facotr
await client.UserFactors.ActivateFactorAsync(verifyFactorRequest, user.Id, smsFactor.Id);

Verify a Factor

// Find the desired user
var user = await client.Users.FirstOrDefault(x => x.Profile.Email == "");

// Find the desired factor
var smsFactor = await user.Factors.FirstOrDefault(x => x.FactorType == FactorType.Sms);

// Verify sms factor
var response = await client.UserFactors.VerifyFactorAsync(verifyFactorRequest, user.Id, smsFactor.Id);

List all Applications

// List all applications
var appList = await client.Applications.Applications().ToArray();

// List all applications of a specific type
var bookmarkAppList = await client.Applications.ListApplications().OfType<IBookmarkApplication>().ToArray();

Get an Application

var createdApp = await client.Applications.CreateApplicationAsync(new CreateBasicAuthApplicationOptions()
                    Label = "Sample Basic Auth App",
                    Url = "",
                    AuthUrl = "",

var retrievedById = await client.Applications.GetApplicationAsync(createdApp.Id);

Create a SWA Application

var createdApp = await client.Applications.CreateApplicationAsync(new CreateSwaApplicationOptions
    Label = "Sample Plugin App",
    ButtonField = "btn-login",
    PasswordField = "txtbox-password",
    UsernameField = "txtbox-username",
    Url = "",
    LoginUrlRegex = "^",

Create an OpenID Application

var createdApp = await client.Applications.CreateApplicationAsync(new CreateOpenIdConnectApplication
    Label = "Sample Client",
    ClientId = "0oae8mnt9tZexampl3",
    TokenEndpointAuthMethod = OAuthEndpointAuthenticationMethod.ClientSecretPost,
    AutoKeyRotation = true,
    ClientUri = "",
    LogoUri = "",
    ResponseTypes = new List<OAuthResponseType>
    RedirectUris = new List<string>
    GrantTypes = new List<OAuthGrantType>
    ApplicationType = OpenIdConnectApplicationType.Native,
    TermsOfServiceUri = "",
    PolicyUri = "",

Call other API endpoints

The SDK client object can be used to make calls to any Okta API (not just the endpoints officially supported by the SDK) via the GetAsync, PostAsync, PutAsync and DeleteAsync methods.

For example, to activate a user using the PostAsync method (instead of user.ActivateAsync):

await client.PostAsync(new Okta.Sdk.HttpRequest
    Uri = $"/api/v1/users/{userId}/lifecycle/activate",
    PathParameters = new Dictionary<string, object>()
        ["userId"] = userId,
    QueryParameters = new Dictionary<string, object>()
        ["sendEmail"] = true,

In this case, there is no benefit to using PostAsync instead of user.ActivateAsync. However, this approach can be used to call any endpoints that are not represented by methods in the SDK.

Rate Limiting

The Okta API will return 429 responses if too many requests are made within a given time. Please see Rate Limiting at Okta for a complete list of which endpoints are rate limited. When a 429 error is received, the X-Rate-Limit-Reset header will tell you the time at which you can retry. This section discusses methods for handling rate limiting with this SDK.

Built-In Retry

You can configure your client to use the default retry strategy if you wish to automatically retry on 429 errors:

var maxRetries = configuration.MaxRetries ?? OktaClientConfiguration.DefaultMaxRetries;
var requestTimeout = configuration.RequestTimeout ?? OktaClientConfiguration.DefaultRequestTimeout;

var client = new OktaClient(apiClientConfiguration: configuration, httpClient: httpClient, retryStrategy: new DefaultRetryStrategy(maxRetries, requestTimeout));

Note: Now, the client is using a NoRetryStrategy but in the next major version the default retry strategy will be automatically added to the client.

Custom Retry

You can build your own retry strategy by implementing the IRetryStrategy interface and pass it to the OktaClient. You will have to read the X-Rate-Limit-Reset header on the 429 response. This will tell you the time at which you can retry. Because this is an absolute time value, we recommend calculating the wait time by using the Date header on the response, as it is in sync with the API servers, whereas your local clock may not be. We also recommend adding 1 second to ensure that you will be retrying after the window has expired (there may be a sub-second relative time skew between the X-Rate-Limit-Reset and Date headers).

JSON Serialization

This SDK provides a DefaultSerializer which has all the logic needed by this SDK to work properly. While the OktaClient constructor allows a custom ISerializer to be set, we highly recommend using the DefaultSerializer, otherwise it is the developer's responsibility to add all the logic required by this SDK to continue working properly. This change was added to support edge cases with custom attributes, but will be removed in the next major release, where the default behavior will be to treat all the custom attributes as strings or arrays when applicable.

Default Serializer Settings

If you have date formatted strings among your Okta custom attributes and you want them not to be parsed to a date type and read them as strings, use the following code:

var serializer = new DefaultSerializer(new JsonSerializerSettings()
    DateParseHandling = DateParseHandling.None,

var client = new Okta.Sdk.OktaClient(new Okta.Sdk.Configuration.OktaClientConfiguration
    OktaDomain = "https://{yourOktaDomain}",
    Token = "{apiToken}"
}, serializer: serializer);

var user = await client.Users.GetUserAsync("");
var stringDate = user.Profile["myCustomDate"];

Configuration reference

This library looks for configuration in the following sources:

  1. An okta.yaml file in a .okta folder in the current user's home directory (~/.okta/okta.yaml or %userprofile\.okta\okta.yaml)
  2. An okta.yaml file in a .okta folder in the application or project's root directory
  3. Environment variables
  4. Configuration explicitly passed to the constructor (see the example in Getting started)

Higher numbers win. In other words, configuration passed via the constructor will override configuration found in environment variables, which will override configuration in okta.yaml (if any), and so on.

YAML configuration

The full YAML configuration looks like:

    connectionTimeout: 30 # seconds
    orgUrl: "https://{yourOktaDomain}"
      port: null
      host: null
      username: null
      password: null
    token: {apiToken}
    requestTimeout: 0 # seconds
      maxRetries: 4

Environment variables

Each one of the configuration values above can be turned into an environment variable name with the _ (underscore) character:

  • and so on

Building the SDK

In most cases, you won't need to build the SDK from source. If you want to build it yourself just clone the repo and compile using Visual Studio.


We're happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.

You can’t perform that action at this time.