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()