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:
- Golang
- JavaScript
go get github.com/ory/[email protected]
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)
}
npm i @ory/client@~1.0.0
import {
Configuration,
- V0alpha2Api
+ OAuth2Api,
+ IdentityApi,
+ FrontendApi,
} from "@ory/client"
const config = new Configuration({
basePath: "https://{your-project}.projects.oryapis.com/",
accessToken: process.env.ORY_API_KEY,
baseOptions: {
withCredentials: true, // Important for CORS
timeout: 30000, // 30 seconds
},
})
const ory = {
- v0alpha2: V0alpha2Api
+ identity: new IdentityApi(config),
+ frontend: new FrontendApi(config),
+ oauth2: new OAuth2Api(config),
}
This client needs an API Key to call some of Ory APIs. Read Authorization with API Keys to learn more.
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: { "[email protected]" },
},
})
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.
- Golang
- JavaScript
// Create
identity, res, err := client.
- V0alpha2Api.AdminCreateIdentity(oryAuthedContext).AdminCreateIdentityBody(ory.AdminCreateIdentityBody{
+ IdentityApi.CreateIdentity(oryAuthedContext).CreateIdentityBody(ory.CreateIdentityBody{
SchemaId: "default",
Traits: map[string]interface{}{
"email": "[email protected]",
},
}).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()
// Create
const identity = await ory
- .v0alpha2.adminCreateIdentity({
- schema_id: "preset://email",
- traits: { email: generateEmail() },
+ .identity.createIdentity({
+ createIdentityBody: {
+ schema_id: "preset://email",
+ traits: { email: generateEmail() },
+ }
})
.then(({ data }) => data)
// Get
const identity = await ory
- .v0alpha2.adminGetIdentity(identity.id)
+ .identity.getIdentity({ id: identity.id })
.then(({ data }) => data)
// Update
const identity = await ory
- .v0alpha2.adminUpdateIdentity(identity.id, {
- schema_id: identity.schema_id,
- traits: { email: "[email protected]", ...identity.traits },
- state: identity.state,
+ .identity.updateIdentity({
+ id: identity.id,
+ updateIdentityBody: {
+ schema_id: identity.schema_id,
+ traits: { email: "[email protected]", ...identity.traits },
+ state: identity.state,
+ }
})
.then(({ data }) => data)
// Delete
- await ory.v0alpha2.adminDeleteIdentity(identity.id)
+ await ory.identity.deleteIdentity({ id: identity.id })
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
.
- Golang
- JavaScript
// 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 // ...
async function example() {
// Browser App
const browerFlow = await ory
- .v0alpha2.initializeSelfServiceRegistrationFlowForBrowsers()
+ .frontend.createBrowserRegistrationFlow()
.then(({ data: flow }) => flow)
// Native App
const browerFlow = await ory
- .v0alpha2.initializeSelfServiceRegistrationFlowWithoutBrowser()
+ .frontend.createNativeRegistrationFlow()
.then(({ data: flow }) => flow)
// Get
const getFlow = await ory
- .v0alpha2.getSelfServiceRegistrationFlow(flow.id)
+ .frontend.getRegistrationFlow({ id: flow.id })
// Update / Submit
const result = await ory
- .v0alpha2.submitSelfServiceRegistrationFlow(flow.id, {
- method: "password",
- password: "some-password",
- traits: { email },
+ .frontend.updateRegistrationFlow({
+ flow: flow.id,
+ updateRegistrationFlowBody: {
+ method: "password",
+ password: generatePassword(),
+ traits: { email },
+ // csrf_token: ... - needed in browser apps
+ }
})
.then(({ data }) => data)
}
Frontend errors
Fetch frontend errors with a simple command - GetFlowError
:
- Golang
- JavaScript
// 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
}
- const error = await ory.v0alpha2
- .getSelfServiceError(errorId)
+ const error = await ory.frontend
+ .getFlowError({ id: errorId })
.then(({ data }) => data)
Logout for native apps
- Golang
- JavaScript
res, err := client.
- V0alpha2Api.SubmitSelfServiceLogoutFlowWithoutBrowser(context.Background()).
- SubmitSelfServiceLogoutFlowWithoutBrowserBody(ory.SubmitSelfServiceLogoutFlowWithoutBrowserBody{
+ FrontendApi.PerformNativeLogout(context.Background()).
+ PerformNativeLogoutBody(ory.PerformNativeLogoutBody{SessionToken: sessionToken}).
SessionToken: sessionToken,
}).
Execute()
const logoutUrl = await ory
- .v0alpha2.SubmitSelfServiceLogoutFlowWithoutBrowser({
- session_token: '...'
+ .frontend.performNativeLogout({
+ performNativeLogoutBody: {
+ session_token: '...'
+ }
})
.then(({ data }) => data.logout_url)
Logout for browser apps
- JavaScript
- const logoutUrl = await ory
- .v0alpha2.createSelfServiceLogoutFlowUrlForBrowsers()
+ .frontend.createBrowserLogoutFlow()
.then(({ data }) => data.logout_url)
Session checking
Checking session is now available in the frontend
module:
- Golang
- JavaScript
// 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()
const session = await ory.
- v0alpha2.
+ frontend.
toSession(sessionToken).then(({ data: session }) => session)
// Session Cookies
const session = await ory.
- v0alpha2.toSession(undefined, "ory_session_...=...")
+ frontend.toSession({
+ cookie: "ory_session_...=...",
+ // xSessionToken: ...,
+ })
.then(({ data: session }) => session)
Permissions & Access Control
Manipulation relationships and checking permissions are now available in the relationship
and permissions
modules,
respectively:
- Golang
- JavaScript
// 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()
// Create a relationship
await ory
- .write
- .createRelationTuple({relationQuery: {/* ... */}})
+ .relationship
+ .createRelationship({createRelationshipBody: {/* ... */}})
// Check a permission
const isAllowed = await ory
- .read
- .getCheck({namespace: "n", /* ... */}})
+ .permission
+ .checkPermission({namespace: "n", /* ... */})
.then(({data}) => data.allowed)