Step 1. Create a Developer Portal account
In order to enable and use our APIs, you first need to register on the Developer Portal.
If you already have an account, go to step 2.
1. Select the environment:
2. On the Login page, click on the Create account link.
3. On the registration page, fill in the required fields and click Continue.
4. On the next page, type in the code you received via email and click Continue.
Step 2. Create a new project
Now that you have an account, you need to create a project on the Developer Portal. A project is an instance that represents your application, a component of it, or simply your workspace in our portal. Although the project will not be shown to your end users, it is associated with your enabled APIs and services, credentials, OAuth consent screen configuration, or subscriptions.
1. Click on the Select a project button in the top bar.
2. On the pop up screen, click on the New project button in the top right corner.
3. On the next screen, type a project name and project ID, or continue with the pre-populated values, and click Create.
Note: You can click on the button at the right end side of the Project ID textbox to generate a new unique project ID.
4. You will be redirected to the Dashboard screen, and a notification under the bell icon will confirm that your project has been created.
Step 3. Configure the OAuth consent screen (only for sensitive APIs)
Developer Portal offers both sensitive and non-sensitive APIs. A sensitive API might need access to the end user's private data, so it is necessary to have the user's consent before they can continue using your application. The user approval will be provided on an OAuth consent screen that you need to configure on the OAuth consent screen page in the left-side menu.
Note: You don't need to configure this screen if you don't intend to use sensitive APIs. You can check if an API is sensitive on the Library page.
1. On the left-side menu, click on the OAuth Consent Screen entry.
2. On the next screen, configure the consent screen for your application.
Application name: The name of your application. This name should accurately reflect your application and be consistent with the application name your users see elsewhere.
Application homepage link: A link to the homepage of your application for reference.
Application privacy policy link: A link for your users to review your privacy policy before providing their consent.
Application term of service link: A link for your users to review your term of service before providing their consent.
Application logo: An image on the consent screen that will help users recognize your application.
3. After entering all required fields, click Save to finish. You will see a preview of how the consent screen is presented to your users.
Step 4. Enable APIs and services in your project
Now that you have a project set up on the Developer Portal, you can enable APIs and services within the project.
Note: Some APIs are only available to internal users or require a subscription to be enabled.
1. On the left-side menu, click on the Library entry.
2. Click on the grid button next to the screen title to browse our library by APIs. Learn more about our browsing view here.
3. In the API library, browse the available APIs and services, then click on the one that you want to use.
4. In the API details screen, click on the Enable button to request access to the API.
Note: If the API you’re trying to enable is a sensitive API and you have yet to configure the OAuth consent screen for your project, the Enable button will not be available. Go to step 3 to learn how to configure the OAuth consent screen.
Step 5. Create OAuth client ID
Before you can use the enabled APIs, you need to create an OAuth client ID. The OAuth client credentials are generated and verified by the Keycloak authentication server.
1. On the left-side menu, click on the Credentials entry.
2. Select the OAuth Client ID tab.
3. Click on the Create new OAuth client ID button.
4. On the next screen, configure your new OAuth client ID.
Name: Name your Client ID or go with the pre-populated name. This name is only used to identify the client in Developer Portal and will not be shown to end users.
Base URL: The base URL of the website to which this client belongs. This is a piece of descriptive information that we use to trace back suspicious activities.
Audience:
You will NOT see this field if there is no sensitive API scope included in your OAuth client ID.
This is the Unifiedpost realm where the end users of your application will authenticate to provide consent to the application.
API scope restrictions:
Keep the API Scope toggle deactivated if you want access to any API scopes in the project.
If you want to restrict which scopes the Client ID has access to, activate the toggle and select the scope(s). Only the scopes of enabled APIs will be available. If the toggle is activated, but no scopes are added, the API request will not work.
Authorized redirect URIs:
You will NOT see this section if there is no sensitive API scope included in your OAuth client ID.
This URL is where the users will be redirected after authenticating with Keycloak, as this is where the authorization server sends the token. You can enter up to 10 redirect URIs for a client ID in Developer Portal.
The redirect URIs you enter must begin with https or http scheme, and should not contain wildcard characters.
If you are making an API request via Postman, you can authorize using the browser and use https://oauth.pstmn.io/v1/callback as a redirect URI.
If you want to get authorized in Swagger, use [swagger URL]/oauth2-redirect.html as the redirect URI.
If you're using this in your web application, try using the callback URL of the page/screen that the user will be redirected to after the consent screen.
5. After entering all required fields, click Save to finish. You will then be redirected to the Credentials screen, where your client ID and client secret are displayed on a popup window.
Step 6. Get authorization token
As mentioned, Developer Portal offers two types of API: sensitive and non-sensitive. Depending on the API type, the authorization token you need to perform the API calls is retrieved in different ways.
Instructions on how to generate a token for the API that you want to use can be found in each API user guide.
Check out the API user guides page for a full list of available user guides.