---
id: overview
title: Overview of sessions, Ory Session Cookies, and Ory Session Tokens
sidebar_label: Session management
---
# Overview
```mdx-code-block
import Tabs from "@theme/Tabs"
import TabItem from "@theme/TabItem"
import { getSdkUrl } from '@site/src/hooks'
import CodeBlock from '@theme/CodeBlock'
```
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](#json-web-token-jwt-support).
:::note
For security reasons, you can't break the isolation between cookies and session tokens.
:::
## Ory session
This is a sample session:
```json
{
"active": true,
"authenticated_at": "2019-08-24T14:15:22Z",
"authentication_methods": [
{
"aal": "aal1",
"completed_at": "2019-08-24T14:15:22Z",
"method": "password"
}
],
"authenticator_assurance_level": "aal1",
"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`](../../reference/api.mdx#operation/initializeSelfServiceLoginFlowForBrowsers) endpoint or [`/self-service/login/api`](../../reference/api.mdx#operation/initializeSelfServiceLoginFlowWithoutBrowser) endpoint and setting `refresh` to `true`
|
### Using Ory Session Cookie
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.
:::
````mdx-code-block
```mdx-code-block
import reactWhoAmI from "!!raw-loader!@site/code-examples/sdk/typescript/src/selfservice/session/whoami-react.tsx"
{reactWhoAmI}
```
```mdx-code-block
{`curl '${getSdkUrl().url}/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.
:::
````mdx-code-block
```mdx-code-block
import goDisableSession from '!!raw-loader!../../../code-examples/sdk/go/frontend/whoami-native.go'
{goDisableSession}
```
```mdx-code-block
import nativeWhoAmI from "!!raw-loader!@site/code-examples/sdk/typescript/src/selfservice/session/whoami-native.ts"
{nativeWhoAmI}
```
```mdx-code-block
{`curl '${getSdkUrl().url}/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:
1. 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.
2. 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.](../../concepts/cache.mdx)
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](../../identities/session-to-jwt-cors.mdx). Read more in the
[Session to JWT](../../identities/session-to-jwt-cors.mdx) 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).
### Use Ory Oathkeeper to convert sessions to JWTs
[Ory Oathkeeper](https://www.ory.com/oathkeeper) is an API Gateway capable of converting sessions to JWTs.
```mdx-code-block
import Mermaid from '@theme/Mermaid';
>+G:ory_session=...
G->>+O:|GET /sessions/whoami
O->>-G:id=... identity.id=...
G->>G:Convert Session to JSON Web Token
G->>+S1:Authorization: Bearer jwt...
S1->>+S2:Authorization: Bearer jwt...
`}/>
```