API authentication
To make calls against your Replicon instance, you'll need to authenticate or authorize access to the instance.
Authenticating on reference pages
You can test calls using the reference pages, providing:
- You are logged in to Replicon and have a reference page open in the same browser, and
- Your instance's 'swimlane' (the three digits preceding .replicon.com in its URL, like sb1, na7, eu1, etc) matches the swimlane shown in the reference page's URL
If you access the reference pages using most links in this user guide, you'll automatically be prompted to log in to Replicon before being sent to the reference page, and the swimlane of the reference page should automatically update to match that of your instance.
However, if, when testing, you want to:
- Use the curl responses provided on the reference pages, or
- Use another user's level of data access,
you should authorize access using token-based authentication
Authorizing using token-based Bearer authentication
Acquiring a token
To generate a token:
- Open the Security API reference page.
You will be prompted to log into your Replicon instance before you can access this page. This way, the reference page will be automatically authenticated for use with your instance.
- Expand the POST /AuthenticationService1.svc/CreateAccessToken2 operation.
You must have an Administrator permission set assigned to use this operation.
- Click Try it out, and paste the following into the edit space:
{
"identity": {
"loginName": "admin"
},
"description": "Token for testing export app",
"unitOfWorkId": "001"
}
You can update the login name in the identity parameter; when you use the token, you'll have access to all data the user you submitted has access to.
You must use a unique string in the unitOfWorkId field each time you generate a new token; the API will always return the same result the ID was originally associated with. So, if you don't update the ID, each new call will return the same token.
- Click Execute.
A successful request will return a token. The token shouldn’t expire, unless you included the Lifetime fields when generating it.
Be sure to keep your token secure, as it allows access to your Replicon data.
Authorizing a reference page using the token
You'll need to enter the token on each reference page you want to test from.
When using token-based authentication, note that:
- The token won't work if you're logged in to Replicon using the same browser; if you're logged in, the API will default to using the credentials of logged in user, not the ones associated with the token.
- For token-based authentication to work, the 'swimlane' (the three digits preceding .replicon.com in its URL, like sb1, na7, eu1, etc) in the URL of the reference page you're working on must match the swimlane in the URL of your Replicon instance.
To authorize a page using a token:
- Copy this token, and open the reference page you want to test from.
- Click Authorize, and paste the token into the Value field.
- Click Authorize, then click Close.
Now, when you carry out test operations, the curl data should be usable, and access should be limited by the user associated with the token.
Authorizing programmatic calls
If you want to make calls programmatically, you’ll first need to authenticate using token-based Bearer authentication. Refer to the following for examples of how to format this type of authentication:
Best practices for coding programmatic calls
The swimlane in URL must be correct to authenticate
Each Replicon instance is hosted on a particular swimlane (sometimes called an endpoint). In the URL https://X.replicon.com/services/, X represents the swimlane, which could be NA2, NA4, EU1, etc, making the URL read https://na3.replicon.com/services/ or similar.
The swimlane assigned to an instance may change from time to time, and the API can only be accessed from your instance’s swimlane.
So, it’s a good idea to include a check in your code, and generate the web service URL dynamically each time you perform a call. And, if you’re having authentication errors, check that you’re accessing the services from the correct swimlane.
You should always include application context with each call
When making a programmatic call, we recommend you reference the purpose of the call in the X-Replicon-Application field of the header. And, each time you make a call of this type, that you include this same context in the X-Replicon-Application field. Maintaining this practice helps with troubleshooting.
For example, if the goal of a call is to add, retain, or remove user profiles, to keep them sync with Replicon, you could include this statement in the header:
"X-Replicon-Application":"CompanyKey_UserSynchronization_1.0"
You'd include this same context any time you add or update users.
FAQs
I received an All access checks failed to authorize operation error
If you see an error like this: All access checks failed to authorize operation '<name of operation>' : At least one of the following permissions are required: ‘<name of permission>’, you’re missing permissions required to perform the operation in question.
For any operation carried out using services, you’ll need the same permissions and products you need to carry out that operation manually within the app. For information on assigning products and permissions, select the links.
Why can’t we use basic authentication?
We don’t support basic authentication since it doesn’t work with certain features, such as multifactor authentication.
Related links
Introduction to the Replicon API
Using the API
Getting started with Replicon's API
Viewing the available API operations
Testing your API calls
