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.

Environments​

Ory Network offers different environments for production, staging, and development. These are called Ory Network projects.

Review rate limits in the Project Rate Limits documentation. To match configuration between projects use the Ory CLI For more information what environments are included on the Ory Network plans, head over to the Pricing page.

danger

Staging and development projects are for test data only! Ory Network doesn't guarantee GDPR-compliant PII handling in staging and development projects.

Development projects​

Development projects provide a free test environment for your projects, with limited rate limits and no custom domain. They are ideal for early-stage development and testing. To create a new development project, use the following command:

ory create project --name "My Development Project"

Staging projects​

Staging projects offer all features of production environment including a custom domain (e.g., https://auth-staging.example.com). Staging projects have lower rate limits than production projects.

To create a new staging project, open the Ory Console, hit "Create new project", and select the Staging environment in the next screen.

Staging projects are suitable for testing your application and its integrations with Ory Network before deploying to production. They provide a more accurate representation of how your application will behave in a production project compared to development projects, without the risk of affecting real users or data.

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_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.
Ory Network

The most flexible and scalable way to manage identi­ties, authen­tication, autho­rization and access control.Explore Ory Network

Explore Ory Network