Manage a Token
Learn how to manage a security token, acquire ideas for sequencing, and download sample code.
Step 1 – Acquire ideas for sequencing (scenario)
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 in 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
- Matt enters his travel dates and origin/destination airport codes then clicks the SEARCH button.
- Matt sees the message "Please wait. We're looking for flights." In 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.
- Texas Fares returns flight availability to Matt for review.
- 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
- Texas Fares tells Matt "Are you new here? Please sign-in or create an account."
- Matt clicks REGISTER and enters his name, email address, credit card number, and (if applicable) frequent flyer number.
- Matt clicks the SAVE button.
- Matt sees the message "Please wait. We're creating your account." In the back-end of Texas Fares:
- Get a session token from your in-house session token manager and 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.
- Get a session token from your in-house session token manager and call the Sabre server:
Scenario step 3 – Begin creating the passenger name record (PNR)
The Texas Fares website begins creating the passenger name record (using the profile name in step 2).
Workflow
- Get a session token from your in-house session token manager
- 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 scenario 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
- Matt selects a seat and clicks CONTINUE.
- In the back-end of Texas Fares: 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.
- Matt is taken to a web page with a graphical seat map (#see tip 6).
- 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
- On the back-end of Texas Fares: 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.
- Matt is taken to a confirmation page containing a final message that says "Success! You're all set."
- What's next? For help with issuing a ticket, see the Issue Air Ticket workflow.
Tips
- Sessionless tokens can be used for multiple traveler requests at the same time and do not need to be refreshed nor rendered invalid.
- This is an optional step to sequencing a passenger name record into your workflow. See also: Intro to PNRs for other sequencing options.
- For details on the required fields for flights in the U.S., see secure flight information requirements in Format Finder (TN customers only).
- 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.
- 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's database; therefore, there is no need to keep the data in your Sabre work area.
- A graphical seat map must be created in-house.
- 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 the data in your Sabre work area.
- 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.
Which token to use
All Sabre APIs support either a session or session-less token for authentication and authorization (and some support both). Rest APIs support session-less tokens, while SOAP APIs support session tokens. View a list of our APIs in the Product Catalog.
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 stateless. 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.
What is a session token?
Session tokens are binary security tokens and are stateful. 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.
How to manage a sessionless token
The following workflow details considerations for how you could manage a given sessionless token at a glance.
- Get one sessionless token once a week.
- Use the same token with every call to Sabre APIs for all your traveler requests.
- Keep track of the time-to-live.
- Design logic to handle sessionless token errors.
- Let it expire.
- Repeat.
Note: We also recommend you code according 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).
- Get a session token.
- Behind the scenes, Sabre allocates a session from your session pool.
- Send the same token with each call to Sabre APIs one traveler request at a time.
- Keep the session token alive by refreshing the session token every 14 minutes.
- Design logic to handle session token errors.
- Return to your in-house session token manager for other requests.*
- Terminate the token when you deem it appropriate (according to your workflow).
- Get new session tokens between 10:00 a.m. and 11:59 p.m. CST Saturday each week after Sabre system maintenance activities.
- 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 Codes | Message |
429 | Too many requests. Your transactions per second (TPS) limits for an API have been exceeded. |
401 | Token has expired. |
SOAP Codes | Message |
USG_IS_BUSY . |
Too many requests. Your transactions per second (TPS) limits for an API have been exceeded. |
SG_INVALID_SECURITY_TOKEN . |
Token has expired. |
See also: the full list of 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" rule
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. 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 it." 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 Session Token Manager
Download our plug-and-play Session Token Manager to manage session tokens, or mirror its logic to create your own in-house token management solution.
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 outlined in steps 1-5.
Step 2 – Get half of your available session tokens/sessions
The downloadable sample was designed with logic to get an "x" number of new session tokens/sessions. We recommend you customize this number to match up 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 any logic to handle errors. We recommend you design logic and code to common errors to prevent a traveler's workflow from being interrupted. See Errors for details.
Related topics
- Learn common workflows. Check out the different ways to accomplish common travel workflows with our Workflows.
- Optimize your workflows. Did you know using a sessionless token can reduce the number of calls to Sabre? See Optimize workflows.
- Learn about the Sabre work area. The Sabre work area is where you build a passenger name record. See Intro to the Sabre Work Area.
- Learn about passenger name records. Identify requirements and get sequencing ideas in Intro to PNRs.
- Start building. Download sample code in your programming language of choice (with readme.md files and more) to start building.