Introduction to Web Services for Concur Expense - Authentication

[tim_chapman]

Web Service for Concur Expense contains a vast array of APIs that can do almost anything within SAP Concur. Most of the APIs are customer-initiated calls into Concur Expense.  As such, security and authentication are critical.

I have been a Technical Consultant at SAP Concur for many years and work on the data interfaces between SAP Concur and it's customers.  I have found the hardest issue facing clients is how to get started with Web Services.  Everything begins with Authentication.  Once you have been authenticated, you can use the other APIs accordingly.

In this post, I will explain the basics of authentication and the most common implementation of it for customers (versus partners).  The complete authentication documentation can be found here.

Introduction

The following steps need to be performed

1. Create a web application - A web application is used to connect to Concur Expense.  The application has permissions (called grants and scopes) of what it is allowed to do within Concur Expense.  When you create a web application, it is best practice to give it the minimum permissions necessary to perform its function.  That way if it ever got compromised, you know what it could have been used for.


2. Obtain a request token - a request token could be thought of as a "temporary password".  It is good for 24 hours and should be safeguarded accordingly.


3. Convert the request token to a refresh token - a refresh token could be thought of as a password.  This value should be protected.  Ideally, only the program needs to know this value.


4. Get an access token - an access token is used by the APIs to interface with Concur Expense.  It is good for 60 minutes.  This token is what Concur Expense will use to know the authentication is successful and what APIs can use the access token.

Applications and Tokens have an expiration date.  If not used, they will be deactivated and will need to be setup again.  It is critical for customers who have Production Sandbox Entities ensure their applications continue to run.

The following is a flow diagram of an ongoing web application once the setup is complete (Steps 1-3)

Ongoing Authentication Flow

Using the detailed instructions below, you should be able to create a web application within your Concur Expense environment and authenticate.  From there, you can explore other APIs to interact with SAP Concur.

 

Detailed Walkthrough

The following instructions can be used for performing these 4 steps.  I have created a Authentication repository written for Postman (found here) to support these steps.  Within the repository are two JSONs.  One is for the authentication collection and the other is a Postman Environment.  I am using a Postman Environment so a customer can create multiple web applications and freely flip between them within Postman by changing the environment.

Step 1 - create the Web Application within SAP Concur (one time setup)

1. Log into SAP Concur with a User with Web Service Administration permission.


2. Navigate to Administration->Company->Authentication Admin
   


3. Choose OAuth 2.0 Application Management.  Please note that if you do not have this option, contact you SAP Account Manager to discuss using Web Services.


4. Click the blue button "+ Create New App"
   
   
   
   1. Ensure the App Description is meaningful. SAP Concur knows if an app is being used, but will not know who is using it. this description should contain a purpose, a name, an organization that can be used years down the road to understand why it exists.
   
   
   2. Allow Grants are used for authentication. For this collection, you need to have refresh_token and password.
   
   
   3. Allow Scopes define what authority the application needs. Each API requires a minimal set of scopes to work. It is best practice to provide the minimum necessary "just in case" of a security breach. You can always add/remove values later. For this collection to work, you don't need any scopes (but you must have at least one for the app to save).  For a detailed list of scopes and corresponding APIs, go here
   
   
   
   


5. Upon clicking Create, you will be presented with the Client ID and Client Secret. SAVE THESE. For the postman collection, these go into the "Current Value" of environment variables clientId and clientSecret
   
   

 

Step 2 - Obtain a temporary Request Token (one time setup)

A request token is only good for 24 hours and is the first step towards a more permanent Token

1. Log into SAP Concur with a User with Web Service Administration permission.


2. Navigate to Administration->Company->Authentication Admin


3. Choose Company Request Token


4. For App ID, put in the ClientID from step 1.5 and click the orange Submit button


5. On the next screen, you will be presented with the Company UUID and the Company request token. SAVE THESE. For the postman collection, these go in to the "Current Value" of the environment variables companyUUID and requestToken.

 

Step 3 - Convert the Request Token to a Refresh Token (one time setup)

A refresh token is good more 6 months every time it is used. You only need to convert from a request token to a refresh token once.

1. Review your environment variables. There is one for datacenterURI. It is currently set for the US2 datacenter. You can use the value at the top of the web browser when you are logged in to determine which data center your entity is on. Besides us2.api.concursolutions.com, ihe other common value is eu2.api.concursolutions.com. Note that various pages on the developer portal may reference this value using several names. Despite these differences in naming conventions, they are all referencing the same thing.
   
   
   
   1. geolocation
   
   
   2. baseURI
   
   
   3. datacenterURI
   
   
   4. InstanceURL
   
   
   5. datacenter
   
   
   
   


2. Assuming you put the values in the correct environment variables, and you saved the environment, you can just run the "(Onetime) Convert Request Token to Refresh Token"
   
   
   
   1. This HTTP Request will update the refreshToken of the environment variables for you based on the "refresh_token" return value.
   
   
   
   

 

Step 4 - Get an Access Token (before every call)

An Access Token has a life expectancy of about 60 minutes before it expires. It is best practice to obtain an access token before each set of calls, or, trap the error from the API call and get a new access token before continuing.

1. Run the "Obtain Access Token" request
   
   
   
   1. This HTTP Request will update the accessToken of the environment variables for you based on the "access_token" return value.
   
   
   
   

 

Conclusion

Using the information in this post, you should be able to build an application and authenticate with Concur Expense.  That is the beginning of your Web Services journey.  From there you can explore the multitude of APIs available and solve you business problem.

Share and Connect

What do you think?  Do you have anything to add? Leave a comment below.

Did you find it useful? Give us a like and share on social media.

Want to know more about SAP Concur? Please follow here.

Want to ask questions about SAP Concur and its offerings? Ask here

Follow my profile for similar content.

Thank you!

[maxarndt-roos]

Hi Tim,

thanks for this great blog post and the detailed instructions.

we currently want to establish a system connection with webservices, but we cannot see the option "OAuth 2.0 Application Management" under Authentication Admin. I have already created a support ticket (case 20742049 ), just asking to get the required admin authorization. However, there is no progress on the ticket.

 

can you help?

Thanks

Max

[tim_chapman]

Hi Max!  Thank you for the case number.  I was able to review it and sent an email to your account manager to assist on obtaining the extra access.  In the meantime, what are some things you are looking to do?

[maxarndt-roos]

Hi Tim,

thanks for the swift reply and for reaching out to our account manager.

 

kind regards

Max

[camilogon]

Thanks Tim!

It is a great article.

Unfortunately i got stuck on the

"Assuming you put the values in the correct environment variables, and you saved the environment, you can just run the “(Onetime) Convert Request Token to Refresh Token”"

What is this (Onetime) Convert Request Token to Refresh Token ? Where can I find it?

Thanks,

Camilo

[michael_cliff]

Hi Camilo,

There's a link to a Postman collection in the blog. One of the requests in that collection is called "Convert Request Token To Refresh Token"—that's what this step is referring to. Once you have the Refresh token, it's valid for 6 months, and that extends every time you call the "Obtain an Access Token" request. So, you should only need to exchange the Request Token once, unless you go more than 6 months without using the Refresh token. In that case, you would need to obtain a new Request Token and exchange it again.

Best regards,
Michael

[bai_ling]

Hi Tim,

Thanks for this information! We have employee information stored in the traveler's profile in Concur.

Is it possible for us to establish the Webservice by creating API to pull the selective information that are needed into SAP employee vendor master for disbursement? For example, bank info and payee name?

 

Best regards,

Ling

[tim_chapman]

Hi Ling!

 

You want to look at the User Provisioning and/or Identity APIs for Concur found here: https://developer.concur.com/api-reference/profile/v4.1.identity.html

At this time, there are no APIs available that can access sensitive information like banking information.  For your implementation, I would anticipate that you have the employee enter the banking into SAP instead of entering it into Concur (which doesn't really need the information).

[boot9w]

Hi - Great post!

I was able to get as far as creating the token(s) but stuck afterwards.  Does anyone have an example of what the basic Postman setup for a User/GET request should look like?  Trying to determine if it is user error (quite possibly) or and access issue.  

Thank you - Jeff

[RickF]

@boot9w  Hi Jeff - Have you checked out the documentation on developer.concur.com?    Here is a link that which I think should be helpful.

SAP Concur Developer Center | Identity v4.1

If you scroll down a little from the top of the page, you will see some of the different URI's that are available.

RickF   

[boot9w]

Hi Rick-

Yes, tried https://us2.api.concursolutions.com/profile/identity/v4.1/Users and getting access denied.  Just not sure if it is my Postman setup or my access, which is why I was hoping for an example to compare to mine. 

[RickF]

@boot9w  -  Hi Jeff

We actually have a sample postman collection published in our User Provisioning Service Implementation Guide.   Here is a link to that page.   

SAP Concur Developer Center | User Provisioning Service Implementation Guide

The sample collection is located near the bottom of the page.   

There is also a six-part series introducing UPS, that you might find helpful to read through.   Here is a link to the first post in the series.

Introducing SAP Concur’ s Identity and User Provis... - SAP Community

I hope this helps.   

RickF

[tim_chapman]

@boot9w - Check the scopes in your application.  For the above, I listed the scopes necessary to get tokens.  Each Concur API requires different scopes.  Based on your post, it looks like you need one or more identity.*.read scopes to be added to your application.

The scopes allow you to control what data each application has access to and what it can do (read versus update).  That way you can prevent accidental misuse.

[boot9w]

Thanks Rick!

I missed the sample collection at the bottom, exactly what I needed.