BookmarkSubscribeRSS Feed

Tutorial: Getting Started With SAS Viya RESTful APIs

Started ‎12-19-2022 by
Modified ‎02-02-2023 by
Views 4,260

It can be frustrating sometimes when you want a quick entry into a new concept or piece of software but feel like you need to wade through pages and pages of documentation first.


In this tutorial I'll show you how to quickly get started with the RESTful APIs in SAS Viya. I'll start by showing you how to authenticate a new session (basically "logging in") and then use that session to retrieve some information from a SAS Viya instance. This is basic stuff, but should provide you with a solid foundation for exploring further.


Introducing Postman

Today we'll be using a convenient API tool called "Postman" to get started with SAS Viya APIs. Postman is a very popular piece of software for building, testing, and using APIs, it's free to download and use straight away, and it supports exporting your work for use with a variety of other tools including Python, Java, or from the command line with tools like curl,which makes it very versatile for our purposes.



All steps provided will assume you've already downloaded and installed Postman. You are also going to need an installation of SAS Viya and some login credentials to work with!



Step 1 - Authentication and Authorization


Authentication and Authorization is a vital first step. We are going to have to work hard for our access_token. Without this, we have access to... nothing!


Creating a Collection


Open up Postman, click the + next to/under Collections, click on the "New Collection" that appears and rename it using the pencil icon under the tab on the right to something helpful like "Viya API Tutorial" and hit enter, although really you can name it anything you like.




Creating your first API request


Next, click the chevron > next to whatever you named your collection on the left, click on "Add a request" and then name it something like "Get Auth" and hit enter:




This will be our first API request.


Now, click the button where it says "GET" and change this to "POST", as this is the type of HTTP method we need for our request. Next to this, where it reads "Enter request URL", type in "{{baseUrl}}/SASLogon/oauth/token" without the quotation marks:




The "{{baseUrl}}" part of this is a variable, and is going to allow us to reuse this API call in other workflows and with other SAS Viya servers, simply by changing the contents of the variable. We'll be using variables like this in a couple of places. 


Next, click the "Authorization" tab, and change the "Type" from "Inherit auth from parent" to "Basic Auth". Next, we'll type in "" without the quotes as our "Username" on the right, and leave the "Password" box empty and alone:




(Using "" as a client id isn't the "right" way to do things in general but will work for our tutorial. A great starter explanation about a better way to set up proper client id and client secret credentials can be found in Joe Furbee's excellent blog post "Authentication to SAS Viya: a couple of approaches".)


Now, click the "Body" tab (we can safely ignore the "Headers" tab), click the "x-www-form-urlencoded" radio box, and in the table below the radio boxes, enter the following values:


username {{username}}
password {{password}}
grant_type password


You'll notice again that rather than hard coding values, we've added two new variables in this step, "{{username}}" and "{{password}}". Your screen should look like something this:




(Incidentally, a "grant_type" of "password" is not typically recommended for production purposes, but works well for our tutorial. Tara St. Clair has a great post about the right way to do things in her blog post Building custom apps on top of SAS Viya, Part Three: Choosing an OAuth flow.)


Finally, we're going to add tiny bit of optional helper code to our API call, that will run in Postman once the API call has completed and will make our life easier down the track. Click on the "Tests" tab and enter:






var res = pm.response.json();
pm.environment.set('access_token', res.access_token);






It should end up looking like this:




This "Test" will run within Postman as soon as the API call is complete, and will set the Postman variable "access_token" to the contents of the access_token field from the API response from the Viya server.  Make sure you click "Save"!


Creating a Postman Environment


Now, let's take stock of the variables we've used so far: We have:

  • baseUrl,
  • username,
  • password, and
  • access_token.

So where do we define the contents of these variables? In the case of Postman, we can conveniently define these using something a feature called "environments".


Introducing Postman Environments

Postman Environments are a convenient way to define variables and their contents and then group them together in a set as different "Environments". You can name these Environment sets whatever you like, and then select from them via a drop down box at the top right corner. This can be very useful if you have different SAS Viya installations you want to work with (server1, server2, etc.) or different credentials (dev, test, prod), making it easy to switch between them while using the same pre-defined API calls.


Let's set up our variable contents. Just like we did with our initial Collection, now we are going to click the vertical "Environments" tab all the way over on the left, click the + next to it, and name it to something helpful like the name of your Viya installation - in my case mine is called "sandpit1" - and hit enter.





We are now ready to define our variables and their initial contents. Make sure you are working inside the horizontal tab corresponding to your new Environment and enter the following values:


baseUrl default The url of your Viya server, e.g.
username default Your Viya username, e.g. johnsmith
password secret Your Viya password, e.g. Orion123
access_token secret Leave this blank, e.g.


Now, make sure you click "Save"!


We are deliberately leaving the initial value of access_token blank here, as this value is provided to us by the Viya server itself once we have made a successful auth request, and will be populated by the little bit of helper code we wrote earlier.


Running the Request


So... guess what? We are ready to run!


Make sure all your work is saved and then click the "Get Auth" tab. Make sure you have your new Environment selected from the dropdown in the top right hand corner (i.e. make sure it doesn't read "No Environment", in my case I needed to use the dropdown to select "sandpit1"), and then click that big blue "Send" button. After a very short wait you see the response from the server similar to the below:




If your request fails or you don't receive a response like the above, go back and double check you've entered everything correctly. Double check you can actually reach the Viya instance via a normal web browser. And double check the username/password credentials you are using in your API call actually work!


Great stuff.  You can't see it from the response itself, but the code we wrote earlier has now populated the access_token Environment variable we defined earlier with the access_token result from the server response.



Step 2 - Using access_token to access... all the APIs!


Phew! Was that hard work?


Well the good news everything else is now easy from here on in.


We can now take our hard-earned access_token (conveniently stashed in the access_token variable for us in our Postman Environment) and use it to access any SAS Viya REST API we like from the documentation at REST APIs for SAS Viya. Any time we need to refresh our access_token we can just send the "Get Auth" request again and Postman along with our helper code will take care of the rest.


Trying Things Out


Let's try it out. Let's retrieve a list of all the reports on the Viya instance.


Start by clicking the ... next to "Viya API Tutorial" and selecting "Add request". Name it something imaginative and crazy like, "List All Reports" (I have a poor imagination).




Next, enter "{{baseUrl}}/reports/reports" into the "Enter request URL" box. Click the "Authorization" tab and next to Type change it from "Inherit auth from parent" to "Bearer Token". You'll notice Postman is clever enough to notice we already have an access_token variable, and helpfully populates {{access_token}} into the Token box on the right.


Make sure you have your Postman Environment selected in the drop down box at the top right, for me it's called "sandpit1", and double check you can see {{access_token}} entered into the box to the right of "Token" (if not, enter it manually to match the below):




That's it. That's all we have to do.


Now we can hit "Send" and it works immediately:




How easy was that?!


This step was easy because we did all the hard work in our previous step getting our access_token when we were setting up our Authentication and Authorization. And the good news is all that hard work is reusable:


  1. We can now take our hard-earned access_token (conveniently stashed in the access_token variable for us in our Postman Environment) and with minimum work use it to simply access any RESTful API call we like from the documentation at REST APIs for SAS Viya.

  2. We can refresh our access_token any time we like (the access_token expires when it's not used and will need to be refreshed from time to time - security) by simply hitting the "Send" button on our "Get Auth" API call, and our little bit of helper code automatically populates the access_token variable.

  3. We can also reuse this API call with any Viya instance we like, we just need to change the baseUrl Environment variable value, or define additional different Postman Environments and simply select them from the drop down when we need them.




Conclusion and Next Steps


It's not hard to see why some people struggle to get into API usage. Many SAS users are from a data science, statistical, or business background rather than a technical one, and understanding Authentication and Authorisation can be quite an entry barrier if you've never worked with RESTful APIs or OAuth before. "Can't I just use my username and password?!" are words I hear often!


The good news is it's not quite as intimidating as it first appears, and these concepts apply not just to SAS but to any system or software that implements RESTful APIs along with standard secure design patterns. You can take the lessons you learn here and apply them to any of these. Cracking the RESTful API nut is satisfying and leads to huge opportunities for automation, integration, and innovation.



If you enjoyed this tutorial then I highly recommend Mary Kathryn Queen's excellent SAS Communities blog post on Using Postman Collections to Execute SAS REST APIs, as it takes some of the concepts I've hinted at in this tutorial and then takes them a little further.




References and Further Reading


Version history
Last update:
‎02-02-2023 09:18 PM
Updated by:



Registration is open! SAS is returning to Vegas for an AI and analytics experience like no other! Whether you're an executive, manager, end user or SAS partner, SAS Innovate is designed for everyone on your team. Register for just $495 by 12/31/2023.

If you are interested in speaking, there is still time to submit a session idea. More details are posted on the website. 

Register now!

Free course: Data Literacy Essentials

Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning  and boost your career prospects.

Get Started

Article Tags