Sessions

Create Session

Create a new Session for a Public Application.

POST

https://api.basistheory.com/sessions

Request

cURL

curl "https://api.basistheory.com/sessions" \
  -H "BT-API-KEY: <PUBLIC_API_KEY>" \
  -X "POST"

JavaScript

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<PUBLIC_API_KEY>");

const session = await bt.sessions.create();

C#

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new SessionsApi(config);

CreateSessionResponse result = apiInstance.Create();

Python

import basistheory
from basistheory.api import sessions_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<PUBLIC_API_KEY>")) as api_client:
    session_client = sessions_api.SessionsApi(api_client)

    session = session_client.create()

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<PUBLIC_API_KEY>"},
  })

  session, httpResponse, err := apiClient.SessionsApi.Create(contextWithAPIKey).Execute()
}

Response

Returns a CreateSessionResponse if the session was created. Returns an error if there were validation errors, or the session failed to create.

{
  "session_key": "<SESSION_API_KEY>",
  "nonce": "4J7SiRvfADwJ9ZqwviJJs8",
  "expires_at": "2023-01-09T20:14:55.2130891+00:00"
}

The session_key should not be shared with any other application. It should only be used by the one creating it. The session will not have any access until it is authorized.

Authorize Session

Authorize a created session with permissions or access rules, using a Private Application.

POST

https://api.basistheory.com/sessions/authorize

Request

cURL

curl "https://api.basistheory.com/sessions/authorize" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "nonce": "4J7SiRvfADwJ9ZqwviJJs8",
    "permissions": [ "token:create", "token:read" ]
  }'

JavaScript

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<PRIVATE_API_KEY>");

const authorizedSession = await bt.sessions.authorize({
  nonce: "4J7SiRvfADwJ9ZqwviJJs8",
  permissions: ["token:create", "token:read"],
});

C#

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new SessionsApi(config);
var authorizeSessionRequest = new AuthorizeSessionRequest()
{
    Nonce = ...
    ExpiresAt = ...
    Permissions = ...
    Rules = ...
};

apiInstance.Authorize(authorizeSessionRequest);

Python

import basistheory
from basistheory.api import sessions_api
from basistheory.model.authorize_session_request import AuthorizeSessionRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<PRIVATE_API_KEY>")) as api_client:
    session_client = sessions_api.SessionsApi(api_client)

    authorizedSession = session_client.authorize(authorize_session_request=AuthorizeSessionRequest(
        nonce="4J7SiRvfADwJ9ZqwviJJs8",
        permissions=[ "token:create", "token:read" ]
    ))

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<PRIVATE_API_KEY>"},
  })

  authorizeSessionRequest := *basistheory.NewAuthorizeSessionRequest("4J7SiRvfADwJ9ZqwviJJs8")
  authorizeSessionRequest.SetPermissions([]string{ "token:create", "token:read" })

  authorizedSession, httpResponse, err := apiClient.SessionsApi.Authorize(contextWithAPIKey).AuthorizeSessionRequest(authorizeSessionRequest).Execute()
}

Request Parameters

Attribute	Required	Type	Default	Description
nonce	true	string	null	A one-time use code to authorize the session
permissions	false	array	[]	An array of Permissions granted to the application tied to the session
rules	false	array	[]	An array of Access Rules granted to the application tied to the session
expires_at	false	string	null	ISO8601 compatible DateTime in which the session will be deleted. By default it is 3 minutes from the session creation date

Either permissions or rules is required to be non-empty when authorizing a Session.

Response

Returns no payload. Returns an error if there were validation errors, or the session authorization failed.

Create Session Response Object

Attribute	Type	Description
session_key	string	The Session API key which should be used for authenticating against Basis Theory API endpoints
nonce	string	A one-time use code to authorize the session
expires_at	date	Expiring date of the Session in ISO 8601 format. Defaults to 3 minutes after the creation date