Setting up ory identity

This guide shows how to set up the necessary dependencies and configurations to integrate Ory's identity management features into your application.

Prerequisites

Before starting, ensure you have:

1. An Ory network account
2. Your Ory project id
3. Your development environment set up with your framework of choice

First, install the Ory SDK for your framework:

JavaScript/Node.js

npm install @ory/client-fetch --save

React

npm install @ory/client-fetch --save

Next.js

npm install @ory/client-fetch @ory/integrations --save

Go

go get github.com/ory/client-go

cURL

For cURL, you don't need to install any SDK, as you'll make direct HTTP requests to the Ory APIs.

2. Set up local development with Ory Tunnel

For local development, you'll need to use Ory Tunnel to connect your local application with Ory's APIs:

macOS

# Install Ory CLI using Homebrew
brew install ory/tap/cli

# Verify installation
ory help

Linux

# Install Ory CLI
curl https://raw.githubusercontent.com/ory/meta/master/install.sh | sh -s ory

# Verify installation
ory help

After installing the CLI, start the tunnel to connect your local application with Ory's APIs:

# Start the tunnel (replace with your project id)
ory tunnel --project <project-id> http://localhost:3000

tip

To learn more about the Ory Tunnel, read the dedicated section of the Ory CLI documentation.

3. Configure the SDK

With Ory Tunnel (Local Development)

When using the tunnel, configure your SDK to use the local tunnel URL:

JavaScript/Node.js

// For local development with tunnel
import { Configuration, FrontendApi } from "@ory/client-fetch"

const baseUrl = process.env.ORY_SDK_URL || "http://localhost:4000"
const ory = new sdk.FrontendApi(
  new sdk.Configuration({
    basePath: baseUrl,
  }),
)

React

// For local development with tunnel
const baseUrl = process.env.ORY_SDK_URL || "http://localhost:4000"
const ory = new sdk.FrontendApi(
  new sdk.Configuration({
    basePath: baseUrl,
  }),
)

Next.js

// For Next.js, create an API route at pages/api/.ory/[...paths].ts
import { createApiHandler } from "@ory/integrations/next"

export default createApiHandler({
  dontUseTldForCookieDomain: true,
})

// Then update your configuration to use relative URLs:
export const ory = new FrontendApi(
  new Configuration({
    basePath: "/api/.ory",
    baseOptions: {
      withCredentials: true,
    },
  }),
)

Go

// For local development with tunnel
configuration := ory.NewConfiguration()
configuration.Servers = []ory.ServerConfiguration{
    {
        URL: "http://localhost:4000",
    },
}

cURL

# When using Ory Tunnel, direct your requests to the tunnel endpoint
curl --request GET \
  --url 'http://localhost:4000/self-service/login/browser' \
  --header 'Accept: application/json'

With Ory Network (Production)

For production environments, configure the SDK to use the Ory Network URL:

JavaScript/Node.js

const { Configuration, FrontendApi } = require("@ory/client-fetch")

// Initialize the SDK
const baseUrl = process.env.ORY_SDK_URL || "http://localhost:4000"
const ory = new sdk.FrontendApi(
  new sdk.Configuration({
    basePath: baseUrl,
  }),
)

React

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

// Initialize the SDK
const ory = new FrontendApi(
  new Configuration({
    basePath: process.env.ORY_SDK_URL || "https://$PROJECT_SLUG.projects.oryapis.com",
    credentials: "include",
  }),
)

Next.js

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

// Initialize the SDK
export const ory = new FrontendApi(
  new Configuration({
    basePath: process.env.ORY_SDK_URL || "https://$PROJECT_SLUG.projects.oryapis.com",
    credentials: "include",
  }),
)

Go

import (
    "context"
    ory "github.com/ory/client-go"
)

func main() {
    configuration := ory.NewConfiguration()
    configuration.Servers = []ory.ServerConfiguration{
        {
            URL: "https://$PROJECT_SLUG.projects.oryapis.com",
        },
    }
    client := ory.NewAPIClient(configuration)
}

cURL

For cURL, you'll include the project URL directly in your requests:

# Example format - specific endpoints will be shown in the authentication section
curl --request GET \
  --url 'https://$PROJECT_SLUG.projects.oryapis.com/self-service/login/browser' \
  --header 'Accept: application/json'