Overview

When a user authenticates, for example by signing in with their username and password, they receive a session. The session is proof that the user is authenticated and allows to interact with the system without the need to re-authenticate for every request.

Sessions can be issued in two formats:

Ory Session Cookie - when the system detects that the interaction is performed through a web browser, a cookie which represents the user's session is stored in the browser.
Ory Session Token - when the system detects that the interaction is performed by a client other than a web browser, for example a native mobile app, a session token is issued to the client.

You can also convert an Ory Session to a JWT, read more about this approach here.

note

For security reasons, you can't break the isolation between cookies and session tokens.

Ory session

This is a sample session:

{
  "active": true,
  "authenticated_at": "2019-08-24T14:15:22Z",
  "authentication_methods": [
    {
      "aal": "aal0",
      "completed_at": "2019-08-24T14:15:22Z",
      "method": "link_recovery"
    }
  ],
  "authenticator_assurance_level": "aal0",
  "devices": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "ip_address": "string",
      "location": "string",
      "user_agent": "string"
    }
  ],
  "expires_at": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "identity": {
    "created_at": "2019-08-24T14:15:22Z",
    "credentials": {
      "property1": {
        "config": {},
        "created_at": "2019-08-24T14:15:22Z",
        "identifiers": ["string"],
        "type": "password",
        "updated_at": "2019-08-24T14:15:22Z",
        "version": 0
      },
      "property2": {
        "config": {},
        "created_at": "2019-08-24T14:15:22Z",
        "identifiers": ["string"],
        "type": "password",
        "updated_at": "2019-08-24T14:15:22Z",
        "version": 0
      }
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "metadata_admin": {},
    "metadata_public": {},
    "recovery_addresses": [
      {
        "created_at": "2019-08-24T14:15:22Z",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "updated_at": "2019-08-24T14:15:22Z",
        "value": "string",
        "via": "string"
      }
    ],
    "schema_id": "string",
    "schema_url": "string",
    "state": "active",
    "state_changed_at": "2019-08-24T14:15:22Z",
    "traits": null,
    "updated_at": "2019-08-24T14:15:22Z",
    "verifiable_addresses": [
      {
        "created_at": "2014-01-01T23:28:56.782Z",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "status": "string",
        "updated_at": "2014-01-01T23:28:56.782Z",
        "value": "string",
        "verified": true,
        "verified_at": "2019-08-24T14:15:22Z",
        "via": "string"
      }
    ]
  },
  "issued_at": "2019-08-24T14:15:22Z"
}

Property	Description
`active`	When set to `true`, the Ory Session is active and can be used to authenticate requests.
`expires_at`	Defines the time when the Session expires. This value depends on the session lifespan configuration.
`authenticated_at`	Indicates the time of the most recent successful authentication. This value is updated when: The end-user authenticates with a second factor such as TOTP The end-user refreshes their session using the `/self-service/login/browser` endpoint or `/self-service/login/api` endpoint and setting `refresh` to `true`

An Ory Session Cookie is issued when the user signs in through the browser-based login flow. To get the session payload, send a request to the /sessions/whoami endpoint.

note

Browser-based applications including single-page applications (SPAs) and server-side rendered apps should use session cookies instead of session tokens.

React
cURL

Checking current session
import { Configuration, FrontendApi, Session } from "@ory/client"
import { useEffect, useState } from "react"

const frontend = new FrontendApi(
  new Configuration({
    basePath: "http://localhost:4000", // Use your local Ory Tunnel URL
    baseOptions: {
      withCredentials: true,
    },
  }),
)

export function checkSession() {
  const [session, setSession] = useState<Session>(undefined)

  useEffect(() => {
    frontend
      // the cookie is automatically sent with the request
      .toSession()
      .then(({ data: session }) => {
        setSession(session)
      })
      .catch((error) => {
        // The session could not be fetched
        // This might occur if the current session has expired
      })
  }, [])

  return session ? (
    <table>
      <tr>
        <th>Session ID</th>
        <th>Expires at</th>
        <th>Authenticated at</th>
      </tr>
      <tr id={session.id}>
        <td>{session.id}</td>
        <td>{session.expires_at || ""}</td>
        <td>{session.authenticated_at || ""}</td>
      </tr>
    </table>
  ) : (
    <div>Loading session data...</div>
  )
}

curl 'https://{project.slug}.projects.oryapis.com/sessions/whoami' \
  -H 'Accept: application/json' \
  -H 'Cookie: ory_kratos_session=MTYzNDIyNzEzN3xEdi1CQkFFQ180SUFBUkFCRUFBQVJfLUNBQUVHYzNSeWFXNW5EQThBRFhObGMzTnBiMjVmZEc5clpXNEdjM1J5YVc1bkRDSUFJRTFDYWtvME5VNVlaVWxvYVZWeWJrUnZhSEF4YmxSV2VVRlhNMWwxVlVGenxXpsk2cL21Dclk3nCoXV41N6bFxvVJSt7CeICy_815Aw=='

Using Ory Session Token

An Ory Session Token is issued when the user authenticates through a client other than a web browser. To get the session payload, send a request to the /sessions/whoami endpoint.

note

Native applications such as desktop applications, mobile applications, or terminal-based apps that do not run inside a browser should use session tokens instead of session cookies.

Go
TypeScript
cURL

Checking current session
package frontend

import (
	"context"
	"fmt"
	"os"

	"github.com/ory/client-go"
)

type oryMiddleware struct {
	ory *ory.APIClient
}

func init() {
	cfg := client.NewConfiguration()
	cfg.Servers = client.ServerConfigurations{
		{URL: fmt.Sprintf("https://%s.projects.oryapis.com", os.Getenv("ORY_PROJECT_SLUG"))},
	}

	ory = client.NewAPIClient(cfg)
}

func CheckSession(ctx context.Context, sessionToken string) (session *client.Session, err error) {
	session, _, err = ory.FrontendApi.ToSession(ctx).
		XSessionToken(sessionToken).
		Execute()
	if err != nil {
		// error revoking the session, for example due to expired token provided
		return nil, err
	}

	return session, nil
}

Checking current session (Typescript SDK)
import { Configuration, FrontendApi } from "@ory/client"

const frontend = new FrontendApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
  }),
)

export async function checkSession(sessionId: string, token: string) {
  return await frontend.toSession({
    xSessionToken: token,
  })
}

curl 'https://{project.slug}.projects.oryapis.com/sessions/whoami' \
   -H 'Accept: application/json' \
   -H 'Authorization: Bearer BRFbGMzTnBiMjVmZEcEdjM1J5YVc1bkRDSUFvME5VNVlaVeWJrUnZhSEF4YmxSV2VVRlhNMWwxVlVGenxXpsk2cLXV41N6bFxvVJSt7CeICy'

JSON Web Token (JWT) support

Sessions are by default not issued as JWTs for two main reasons:

Sessions can end at any point in time, indicating that the user is no longer signed in. With JWTs, it's difficult to determine if a session is still valid before the token expires.
Sessions can be updated and changed at any point in time, for example, when the user updates their profile. Such change can't be easily reflected in a JWT before it is refreshed.

Ory Network employs a session caching mechanism to reduce the latency for toSession / /sessions/whoami endpoint calls across the globe so that latency is not an issue for users. Read more about session caching.

If you don't want to make repeated calls to toSession / /sessions/whoami, or you need to use JWTs in your setup, you have several options:

Recommended: Use Session to JWT. Read more in the Session to JWT documentation.
Alternative: Convert sessions to JWTs on your entry point. You then have the option to add caching to further reduce the number of API calls made. More information on this approach is available in the section below.

Use Ory Oathkeeper to convert sessions to JWTs

info

Ory Oathkeeper is an API Gateway capable of converting sessions to JWTs.

Overview

Ory session​

Using Ory Session Cookie​

Using Ory Session Token​

JSON Web Token (JWT) support​

Use Ory Oathkeeper to convert sessions to JWTs​

Ory session

Using Ory Session Cookie

Using Ory Session Token

JSON Web Token (JWT) support

Use Ory Oathkeeper to convert sessions to JWTs