Skip to main content

Develop applications on your local machine

To create your first project on the Ory Network, install the Ory CLI:

Install the Ory CLI using homebrew on macOS:

brew install ory/tap/cli
cli help

and create your first project (it's free):

ory create project --name "Documentation example"

Once the project is created, you have access to Ory's APIs.

Ory APIs​

There are two main API types available in Ory:

  • Admin APIs, which are often used by the application backend, offer privileged access that's not available to end users. To use Admin APIs, you need an Ory Network API Key.

    tip

    Read Authorization with API Keys to learn more about API Keys in the Ory Network.

  • Public APIs, which are often used by the application frontend, don't require an Ory Network API key because:

    • they don't require authorization and can be accessed by any client, for example, an application's login page.
    • they implement a protocol that defines what authorization mechanism must be used, for example, OAuth2 Client Credentials.

Both APIs are available at your project's domain:

https://{project.slug}.projects.oryapis.com

# When you use a custom domain with Ory:
# https://ory.your-custom-domain.com

This endpoint is your SDK URL. Use it when configuring Ory SDKs and tools.

import { Configuration, IdentityApi } from "@ory/client"

const identity = new IdentityApi(
  new Configuration({
    basePath: "https://ory.your-custom-domain.com",
    baseOptions: {
      withCredentials: true,
    },
  }),
)

For a full reference of APIs check out the REST and gRPC API documentation.

API Keys​

API Keys are used to authorize privileged operations. For example, you must use an API Key to call the Admin API, which allows you to delete users. You can create API Keys in the Ory Console.

Follow these steps:

  1. Go to the Ory Console.
  2. Go to Access & APIs.
  3. Click the + icon in the API Keys section.
  4. Enter the API Key name and click Create API Key.
  5. Copy the created API Key from the prompt that shows at the bottom right of the screen.

Local development​

To make login easy and secure, Ory uses cookies to manage session in browser applications. Ory additionally deploys CSRF cookies to protect against CSRF attacks. We recommend taking a deep-dive into Ory's security model if you are not familiar with the concepts.

Ory also supports advanced SSO capabilities based on OpenID Connect. For system that do not require an enterprise SSO solution, we recommend sticking to session cookies.

When developing locally, your application is often exposed at the localhost domain. Ory APIs must be available on the same domain (so localhost) as your application to avoid issues with third-party cookie (e.g. when using Ory Session Cookies). The easiest way to expose Ory on your localhost domain is to use the Ory CLI Tunnel.

Copy the project slug from your project's Connect page and start the Ory Tunnel. Here we assume that your app runs on http://localhost:3000:

ory tunnel --dev --project {project.id-or-project.slug} \
  http://localhost:3000

Running this commands opens the 4000 port on your local machine. The URL http://localhost:3000 is where your application is available. The --dev flag disables a few security checks to make local development easier. After starting the Tunnel, test it by performing the registration flow: http://localhost:4000/ui/registration.

You can now start developing locally. Make sure to send any HTTP calls you make to http://localhost:4000 and not https://{your-slug}.projects.oryapis.com. For example, when you configure the Ory SDK (here in Node.js):

import { Configuration, FrontendApi } from "@ory/client"

const frontend = new FrontendApi(
  new Configuration({
    // Replace
    //  basePath: "https://{project.slug}.projects.oryapis.com",
    // with
    basePath: "http://localhost:4000",
    baseOptions: {
      withCredentials: true,
    },
  }),
)

const { data: login } = await frontend.createBrowserLoginFlow()
const { data: session } = await frontend.toSession()
// ...

Only the FrontendApi needs to access the Ory Tunnel. Administrative APIs like IdentityApi can be accessed directly from your project slug, although they also work via the Ory Tunnel.

Limitations​

Using the Ory Tunnel has two key limitations currently.

  • Your local machine is usually available on both localhost and 127.0.0.1. For the browser these two domains are different domains. Cookies set on localhost will not be sent in requests to 127.0.0.1 and vice versa. If you encounter cookie issues, make sure that all of your requests are sent to localhost and not 127.0.0.1.
  • WebAuthn does not support cross-domain use currently. We are working together with the W3C to figure out solutions.