How to manage a token

Learn how to manage a security token, get ideas for sequencing, and download sample code.

Basic Steps

Prerequisites

Verify with your Sabre account manager that you have access to the APIs you wish to call. Check API documentation to identify the supported token type for a given Sabre API.


Step 1 — Get ideas for sequencing (scenario)

Topics

Introduction

The following scenario demonstrates the front-end and back-end workflow for Texas Fares, a small (and completely fictitious, for demonstration purposes only) online travel agency with less than 100 employees. The business model for the Texas Fares website is to search for the cheapest flights available within the state of Texas.

The Texas Fares website receives less than 100 booking requests per month. Having anticipated and estimated this traffic with its Sabre account manager, Texas Fares was assigned 50 session tokens/sessions and has access to consume sessionless tokens. Given a sessionless token can be used for multiple traveler requests, Texas Fares usually uses one sessionless token at any given time.

To reduce the number of calls to Sabre, Texas Fares uses sessionless tokens whenever possible, and has created simple logic to manage sessionless tokens, in addition to an in-house session token manager.

In the following scenario, the leisure traveler "Matt" (a new user of Texas Fares), conducts a search on the Texas Fares website for flights from Dallas-Fort Worth International Airport (DFW) to Houston William Hobby Airport (HOU).

Scenario Step 1 – search/shop for flights

Matt goes to the Texas Fares website to search for flights.

Workflow

  1. Matt enters his travel dates and origin/destination airport codes then clicks the SEARCH button
  2. Matt sees the message "Please wait. We're looking for flights."
    On the back-end of Texas Fares:
    • Get a sessionless token (#see tip 1)
    • Call the Sabre server:
      • Call the (REST) Bargain Finder Max API for flight availability
      • The API returns the flight information that matches Matt's criteria
    • Extract the flight information (including flight price and flight number) from the response
  3. Texas Fares returns flight availability to Matt for review
  4. Matt finds a flight and clicks NEXT

Scenario Step 2 – begin creating the traveler profile

Matt is asked to enter his travel details and register for a new account. This step (#see tip 2) obtains traveler information that is used to create the passenger name record in step 3.

Workflow

  1. Texas Fares tells Matt "Are you new here? Please sign-in or create an account."
  2. Matt clicks REGISTER and enters his name, email address, credit card number and frequent flyer number
  3. Matt clicks the SAVE button
  4. Matt sees the message "Please wait. We're creating your account."
    On the back-end of Texas Fares:
    • Get a session token from your in-house session token manager
    • Call the Sabre server:
      • Call the Create Profile Objects API with a name for Matt's traveler profile in <ProfileName="MattTravelProfile">
      • The API returns a success message
    • Keep <ProfileName="MattTravelProfile"> for step 3
    • Return the session token to your in-house session token manager for other requests

Scenario Step 3 – begin creating the passenger name record

The Texas Fares website begins creating the passenger name record (using the profile name in step 2).

Workflow

  1. Get a session token from your in-house session token manager
  2. Call the Sabre server:
    • Call the Create Passenger Name Record API with the secure flight information (#see tip 3) the profile name from step 2 <UniqueID ID="MattTravelProfile"> (#see tip 4) and the flight price and flight number from step 1
    • Call the Create Profile Objects API with a name for Matt's traveler profile in <ProfileName="MattTravelProfile">
    • The API returns a success message with the record locator <ItineraryRef ID="ABCDEF">
    • Extract the <ItineraryRef ID="ABCDEF"> for step 5 (#see tip 5) and Matt's flight price and flight number for step 4
    • Return the session token to your in-house session token manager for other requests

Scenario Step 4 – Get seat availability

The Texas Fares website has created an in-house graphical seat map, allowing Matt to see a visual representation of seat availability.

Workflow

  1. Matt selects a seat and clicks the CONTINUE button
  2. On the back-end of Texas Fares:
    • Call the Sabre server:
      • Get a session token from your in-house session token manager
      • Call the Seat Map API with Matt's flight information to get seat availability
      • The API returns seat availability information for the selected flight
    • Extract the seat availability information from the API response
  3. Matt is taken to a web page with a graphical seat map (#see tip 6)
  4. Matt finds a (free) seat and clicks FINISH
    • Extract the seat number for step 5

Scenario Step 5 – book the seat

Texas Fares books the seat.

Workflow

  1. On the back-end of Texas Fares:
    • Call the Sabre server:
      • Get a session token from your in-house session token manager
      • Call the Passenger Details API with the session token, the passenger name record ID (ItineraryRef ID="ABCDEF") (#see tip 7) and Matt's seat number to end the passenger name record (PNR) (#see tip 8)
      • The API returns a success message
  2. Matt is taken to a confirmation page containing his final itinerary that says, "Success! You're all set."
  3. What's next? For steps to issue a ticket, see the issue air ticket workflow.

Tips

  1. Sessionless tokens can be used for multiple traveler requests at the same time and do not need to be refreshed nor rendered invalid.
  2. This is an optional step to sequencing a passenger name record into your workflow. See also: Sabre APIs 101: intro to PNRs for other sequencing options.
  3. For details on the required fields for flights in the U.S., see secure flight information requirements in Format Finder (TN customers only).
  4. For the Create Profile Objects API, the traveler's "profile name" element is called ProfileName. On the other hand, this element is called UniqueID.ID in the Create Passenger Name Record API.
  5. Once you obtain UniqueID.ID, there is no need to use the same session token, as the passenger name record is already stored in Sabre; therefore, there is no need to keep data in your Sabre work area.
  6. A graphical seat map must be created in-house.
  7. Once you obtain ItineraryRef.ID, there is no need to use the same session token, as the passenger name record is already stored in Sabre; therefore, there is no need to keep data in your Sabre work area.
  8. To end the passenger name record via the Passenger Details API, use <EndTransaction Ind="true">

Step 2 — Learn about our tokens

Learn more about the security tokens used to connect to Sabre APIs.

Topics

Which token to use

All Sabre APIs support either a session or sessionless token for authentication and authorization (and some support both). Check the "API Information" box (on the API's documentation page) to determine the supported token type. Go to the list of Sabre APIs.

When tokens expire

Both session and sessionless tokens expire in one week (i.e. 604800 seconds). However, session tokens must be refreshed and must always be rendered invalid; full details are described below.

What is a sessionless token

Sessionless tokens use the OAuth 2.0 token protocol and are state-less. Therefore, tokens do not require a back-end session, do not need to be refreshed, do not need to be rendered invalid, can be used for concurrent requests, and are not affected by Sabre session maintenance activities.

See #how to manage a sessionless token.

What is a session token

Session tokens are binary security tokens and are state-ful. Therefore, tokens require a back-end session, must be refreshed, must always be rendered invalid (according to your workflow), cannot be used for concurrent requests, and are affected by Sabre session maintenance activities.

See #how to manage a session token.

How to manage a sessionless token

The following workflow details considerations for how you could manage a given sessionless token (at-a-glance).

  1. Get one sessionless token once a week.
  2. Use the same token with every call to Sabre APIs for all of your traveler requests.
  3. Keep track of the time-to-live.
  4. Design logic to handle sessionless token errors.
  5. Let it expire.
  6. (Repeat)

NOTE we also recommend you code to each API's transactions per second (TPS) limit. Contact your Sabre account manager for limits.

How to manage a session token

The following workflow details considerations for how you could manage a given session token (at-a-glance).

  1. Get a session token.
  2. (Behind the scenes, Sabre allocates a session from your session pool).
  3. Send the same token with each call to Sabre APIs one traveler request at a time.
  4. Keep session token alive by refreshing the session token every 14 minutes.
  5. Design logic to handle session token errors.
  6. Return to your in-house session token manager for other requests.*
  7. Terminate the token when you deem appropriate (according to your workflow).
  8. Get new session tokens between 10:00 a.m. and 11:59 p.m. CST Saturday each week after Sabre system maintenance activities.
  9. (Repeat)

NOTE we also recommend you code to each API's transactions per second (TPS) limit. Contact your Sabre account manager for limits.

How to handle sessionless token expirations

A sessionless token obtained from the REST sessionless token endpoint can be used to call SOAP APIs (and vice versa). The following details considerations for how to handle sessionless token expirations (at-a-glance).

REST Keep track of the time-to-live in expires_in (in seconds).

SOAP A SOAP sessionless token time-to-live must be calculated in-house. Count-down the time-to-live from the time at which the token was obtained up to the expiration of 604800 seconds (minus a few seconds for latency).

What are the most common error messages to code

  • REST 429 too many requests. Too many requests. Your transactions per second (TPS) limits for an API have been exceeded.
  • REST 401 Unauthorized. Token has expired.
  • SOAP USG_IS_BUSY. Too many requests. Your transactions per second (TPS) limits for an API have been exceeded.
  • SOAP USG_INVALID_SECURITY_TOKEN. Token has expired.

See also: the full list of Sabre APIs: errors.

Why you need to keep track of session tokens

You need to keep track of how many session tokens are active, so you don't run out of session tokens/sessions you can obtain.

The "+1 Sabre side, -1 your side" session rule explained

The "+1 Sabre side, -1 your side session rule" is much like the concept of a library where you borrow a book, read it, and give it back. And there is a limit on the number of books you are allowed to borrow from your local library.

  • Borrow a book. When you get a session token (using the Create Session API), you automatically create a session on the Sabre side. In other words, 1 session on the Sabre side means -1 session tokens you have available to use. That's one less book you can borrow from the library.
  • Read a book. Run your requests according to your workflow.
  • Ask for an extension. You need to tell the Sabre server—"this is an interesting book, I'm still reading." Keep the session token refreshed (using the Refresh Session API).
  • Return a book. You need to tell the Sabre server—"I'm finished reading." Time to return the book so you can borrow another one later. You must always render a session token invalid (using the Close Session API) in order to close the session to Sabre. In other words, -1 session on the Sabre side, means +1 session tokens available to use on your side.

What is a session pool

A session pool is the number of session tokens/sessions you are allowed to have active at one time. If you were allotted 50 session tokens by your Sabre account manager, that means your session pool has 50 sessions. To close a session, you must render a session token invalid (using the Close Session API).

Why a session is needed

Some of our APIs require synchronous access deep within the Sabre universe. We've made it easier by establishing a session automatically when you get a session token. The only thing you need to do is keep track of how many session tokens are active.

How/when to refresh a session token

Call the Refresh Session API every 14 minutes. A session token/session is rendered invalid after 15 minutes of inactivity. We recommend you design logic to refresh a session token every 14 minutes.

How/when to terminate a session token

Call the Close Session API to render a session token invalid. (Include the values for eb:ConversationId, eb:CPAId and wsse:BinarySecurityToken). You must always render a session token/session invalid according to your workflow, in order to close your session to Sabre, and return your session token/session resources.

How to design around session maintenance activities

A Sabre system maintenance and house-keeping application runs every Sunday morning at 00:15 U.S. CST. It takes about five minutes to run worldwide and clears every Sabre work area in Sabre; it also closes/clears all active session tokens. In addition, once the application begins to run, all logged-in Sabre users are required to log-out and log-in again.

Design logic to terminate active session tokens (using the Close Session API) and get new session tokens (using the Create Session API) between 10:00 a.m. and 11:59 p.m. CST Saturday each week. If your session pool is not refreshed, your active session tokens will be rendered invalid and you will receive a USG_INVALID_SECURITY_TOKEN error.


Download sample code for a session token manager

Download our plug-and-play session token manager to manage session tokens, or mirror the logic to create your own in-house token management solution.

Topics

Introduction

We recommend you download a plug-and-play (Java) session token manager solution and configure each value based on the following best practices (or create a custom solution with similar logic).

Scenario

Texas Fares was assigned 50 session tokens/sessions by its Sabre account manager. Texas Fares consists of a single application instance designed with the following logic to manage session tokens/sessions.

Step 1 – Download the session token manager

Download the Session Token Manager (on GitHub). Configure each value based on the best practices in steps 1-5.

Step 2 – Get half of your available session tokens/sessions

The downloadable sample was designed with logic to get "x" number of new session tokens/sessions. We recommend you customize this number to coincide with half of the available session tokens/sessions you were assigned by your Sabre account manager. For example, a single travel application like Texas Fares would configure its session token manager to get 25 session tokens/sessions.

Step 3 – Use one session token one traveler request at a time

Get a session token from your session token manager for each call to Sabre APIs one traveler request at a time and return the token back to your session token manager when complete. If the application already contains an active session token, it will use a token from the session pool. If not, it will get a new session token/session. You may also wish to do multi-threaded workflows, in which you use one session token/session for each of the transactions for a given traveler.

Step 4 – Determine a time interval to refresh session tokens

The downloadable sample was designed with logic to refresh session tokens every 10 minutes. We recommend you customize this number to refresh a session token/session every 14 minutes. A session token is rendered invalid after 15 minutes of inactivity.

Step 5 – Specify a time around weekly Sabre session maintenance

The downloadable sample was designed with logic to render session tokens/sessions invalid and get new session tokens/sessions following Sabre session maintenance. The time window within the sample is a placeholder (which is an invalid) value. You must customize this time to occur between 10:00 a.m. and 11:59 p.m. CST Saturday each week to terminate active session tokens/sessions and get new ones during this time period.

Design logic to handle errors

The downloadable sample does not contain logic to handle errors. We recommend you design logic and code to common errors to prevent a traveler's workflow from being interrupted. See Sabre APIs: errors for details.


What's next?

How to navigate the Sabre universe

Get access to Sabre APIs documentation and explore other customer tools.


Related topics


Frequently asked questions (FAQs)

What happens if a traveler is in the middle of a transaction when Sabre weekly maintenance starts to run?
If a pooled session is in use the state of any transaction in progress must be persisted locally or it will be lost. If a booking is in progress, save to the Sabre work area to store changes, render the session token invalid and get a new token, then retrieve the PNR to continue.

What happens if I call a SOAP API during Sabre weekly maintenance?
When a SOAP API call is issued during the 5 minute warning period before Sabre weekly maintenance runs (00:15-00:20 CST) a warning will be returned. The error will indicate a number between 01 to 05 based on the time remaining before Sabre weekly maintenance begins. For example:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_AirAvailRS xmlns="http://webservices.sabre.com/sabreXML/2003/07"
xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
<Errors>
    <Error ErrorCode="SessionFailure-103" Severity="High" ErrorMessage="Parameter not supported">
        <ErrorInfo>
        <Message>SYSTEM HOUSKPING REQUIRES AAA TO BE CLEARED RE-ENTER LAST INPUT THEN COMPLETE OR END TRANSACTIONS IN ALL AREAS ENTER SOALL WITHIN 04 MINUTES AND THEN SIGN BACK IN TO CONTINUE WORKING</Message>
        </ErrorInfo>
        </Error>
        </Errors>
    </OTA_AirAvailRS>
    

What happens if I call a SOAP API while Sabre weekly maintenance is running?
If a SOAP API call is issued while Sabre weekly maintenance is running (00:20 to approximately 00:25 CT) you may receive an error that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_AirAvailRS xmlns="http://webservices.sabre.com/sabreXML/2003/07"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Errors>
    <Error ErrorCode="SessionFailure-103" Severity="High"
ErrorMessage="Parameter not supported">
        <ErrorInfo>
        <Message>1SYSTEM HOUSKPING - ALL AREAS SIGNED OUT SIGN BACK IN TO CONTINUE WORKING
    </ErrorInfo>
    </Error>
</Errors>
</ OTA_AirAvailRS>

What happens if I don't get all new session tokens after Sabre session maintenance?
SOAP API calls issued after NORM OAA runs will return a USG_INVALID_SECURITY_TOKEN error.


Stack Overflow

Ask a question with the Stack Overflow community.
Ask Questions