Skip to main content

SDK V1 upgrade guide

We are excited to announce the release of version 1.0 of Ory's Software Development Kits (SDKs) for all major languages. As part of releasing version 1.0, we have streamlined naming conventions and improved the API documentation.

History​

Ory SDKs have been around for a while and have gone through several transformations. We always relied on openapi-generator to auto-generate SDKs from our OpenAPI specifications.

Backwards compatibility​

Versions prior to 1.0 will remain functional and compatible with APIs offered on the Ory Network. However, we will no longer be maintaining these versions. We recommend that you upgrade to the latest version of the SDKs by the end of January 2023.

Upgrade guide​

Let's take a look at the changes we made to the SDKs and some examples of how to upgrade your code. We will use Golang for the examples, but the changes are similar for all languages.

In essence, what is changing are naming conventions, not payloads or functionality. Let's create a new SDK client for the examples below:

go get github.com/ory/client-go@1.0.0
import ory "github.com/ory/client-go"

var client = NewSDK()

// Use this context to access Ory APIs which require an Ory API key.
var oryAuthedContext = context.WithValue(context.Background(), ory.ContextAccessToken, os.Getenv("ORY_API_KEY"))

func NewSDK() *ory.APIClient {
  conf := ory.NewConfiguration()
  conf.Servers = ory.ServerConfigurations{{
    URL: "https://{your-project}.projects.oryapis.com/",
  }}

  // If you want the SDK to use a custom HTTP Client, set:
  //  conf.HTTPClient = &http.Client{ /* ... */ }

  return ory.NewAPIClient(conf)
}

JavaScript / TypeScript​

How you pass arguments to the JavaScript SDK has changed. Previously, parameters would be a list of arguments:

await ory.frontend.toSession(undefined, "ory_session_...=...")

Now, parameters are passed as an object:

ory.frontend.toSession({
  cookie: "",
  // xSessionToken: result.session_token,
})

Sending request bodies has also changed. Previously, you would pass the body as the first argument:

ory.v0alpha2.submitSelfServiceRegistrationFlow(flow.id, {
  method: "password",
  password: "some-password",
  traits: { email },
  // csrf_token: ... - needed in browser apps
})

To pass the response body, use the function name and append Body. For example updateRegistrationFlow becomes updateRegistrationFlowBody :

await ory.frontend
  .updateRegistrationFlow({
    flow: flow.id,
    updateRegistrationFlowBody: {
      method: "password",
      password: "some-password",
      traits: { "some@email.com" },
    },
  })

Unfortunately this naming convention is due to an OpenAPI 3.x limitation. We wish the body would just be body, but it is currently not possible.

Identity management​

Generally, identity (and their sessions) management APIs have moved in the SDK from tag v0alpha2 to identity. APIs requiring authorization are no longer prefixed with admin for better readability. Most identity APIs require authorization.

// Create
    identity, res, err := client.
-   V0alpha2Api.AdminCreateIdentity(oryAuthedContext).AdminCreateIdentityBody(ory.AdminCreateIdentityBody{
+   IdentityApi.CreateIdentity(oryAuthedContext).CreateIdentityBody(ory.CreateIdentityBody{
      SchemaId: "default",
      Traits: map[string]interface{}{
        "email": "hello@example.org",
      },
    }).Execute()

// Get
-   identity, res, err := client.V0alpha2Api.AdminGetIdentity(oryAuthedContext, created.Id).Execute()
+   identity, res, err := client.IdentityApi.GetIdentity(oryAuthedContext, created.Id).Execute()

// Update
  identity, res, err := client.
-   V0alpha2Api.AdminUpdateIdentity(oryAuthedContext, toUpdate.Id).AdminUpdateIdentityBody(ory.AdminUpdateIdentityBody{
+   IdentityApi.UpdateIdentity(oryAuthedContext, toUpdate.Id).UpdateIdentityBody(ory.UpdateIdentityBody{
      Traits: map[string]interface{}{
        "email": "dev+not-" + x.NewUUID().String() + "@ory.sh",
      },
    }).Execute()

// Delete
-   res, err := client.V0alpha2Api.AdminDeleteIdentity(oryAuthedContext, identity.Id).Execute()
+   res, err := client.IdentityApi.DeleteIdentity(oryAuthedContext, identity.Id).Execute()

Frontend APIs​

APIs used in the frontend (e.g. signup, registration, ...) have moved from tag V0alpha2Api to frontend and are no longer prefix with SelfService. This improves readability significantly as you can see in the following example:

  const flow = await ory
-   .v0alpha2.initializeSelfServiceSettingsFlowForBrowsers()
+   .frontend.createBrowserSettingsFlow()
    then(({ data: flow }) => flow)

Below you find examples for the error and native/browser app registration flow. Changes to verification, recovery, settings, and login methods are analogous.

Login, registration, recovery, verification, and settings APIs​

Login, registration, recovery, verification, and settings APIs no longer use the SelfService prefix and WithoutBrowser has been changed to Native. Additionally, updating a flow (by filling the form out) has been changed from Submit to Update.

  // Browser App
  flow, res, err := c.
-   V0alpha2Api.InitializeSelfServiceRegistrationFlowBrowser(ctx).
+   FrontendApi.CreateNativeRegistrationFlow(ctx).
    Execute()


  // Native App
  flow, res, err := c.
-   V0alpha2Api.initializeSelfServiceLoginFlowForBrowsers(ctx).
+   FrontendApi.CreateBrowserRegistrationFlow(ctx).
    Execute()
  // if err != ...

  result, res, err := c.
-   V0alpha2Api.SubmitSelfServiceRegistrationFlow(ctx).
+   FrontendApi.UpdateRegistrationFlow(ctx).
    Flow(flow.Id).
-   SubmitSelfServiceRegistrationFlowBody(
+    UpdateRegistrationFlowBody(
-     ory.SubmitSelfServiceRegistrationFlowWithPasswordMethodBodyAsSubmitSelfServiceRegistrationFlowBody(
+     ory.UpdateRegistrationFlowWithPasswordMethodAsUpdateRegistrationFlowBody
-       &ory.SubmitSelfServiceRegistrationFlowWithPasswordMethodBody{
+       &ory.UpdateRegistrationFlowWithPasswordMethod{
          Method:   "password",
          Password: password,
          Traits:   map[string]interface{}{"email": email},
            }),
    ).Execute()

  // if err != ...
  if result.Session == nil // ...

Frontend errors​

Fetch frontend errors with a simple command - GetFlowError:

  // Use a stub error
  var errorId = "stub:500"

- func getError() *ory.SelfServiceError {
+ func getError() *ory.FlowError {
    e, res, err := client.
-     V0alpha2Api.GetSelfServiceError(context.Background()).
+     FrontendApi.GetFlowError(context.Background()).
      Id(errorId).Execute()
    // if err != nil ...
    return e
  }

Logout for native apps​

    res, err := client.
-     V0alpha2Api.SubmitSelfServiceLogoutFlowWithoutBrowser(context.Background()).
-       SubmitSelfServiceLogoutFlowWithoutBrowserBody(ory.SubmitSelfServiceLogoutFlowWithoutBrowserBody{
+     FrontendApi.PerformNativeLogout(context.Background()).
+       PerformNativeLogoutBody(ory.PerformNativeLogoutBody{SessionToken: sessionToken}).
        SessionToken: sessionToken,
      }).
      Execute()

Logout for browser apps​

- const logoutUrl = await ory
-   .v0alpha2.createSelfServiceLogoutFlowUrlForBrowsers()
+   .frontend.createBrowserLogoutFlow()
    .then(({ data }) => data.logout_url)

Session checking​

Checking session is now available in the frontend module:

  // Session Tokens
    res, err := client.
-   V0alpha2Api.
-   FrontentApi.
    ToSession(context.Background()).
    XSessionToken(sessionToken).Execute()

  // Session Cookies
    session, res, err := client.
-   V0alpha2Api.
-   FrontentApi.
    ToSession(context.Background()).
    Cookie("ory_session_...=...").Execute()

Permissions & Access Control​

Manipulation relationships and checking permissions are now available in the relationship and permissions modules, respectively:

  // Create a relationship
  res, _, err := client.
-   WriteApi.
-   CreateRelationTuple(context.Background()).
-   RelationQuery(query).
+   RelationshipApi.
+   CreateRelationship(context.Background()).
+   CreateRelationshipBody(query).
    Execute()

  // Check a permission
  res, _, err := client.
-   ReadApi.
-   GetCheck(context.Background()).
+   PermissionApi.
+   CheckPermission(context.Background()).
    Namespace(r.Namespace).
    Object(r.Object).
    Relation(r.Relation).
    Execute()