Securely invoking a Client Endpoint in Ballerina

Authentication of HTTP endpoints

Chanaka Lakmal
Ballerina Swan Lake Tech Blog



NOTE: All the Ballerina codes in this article are tested and compatible with Ballerina version 0.980.0

What is Ballerina

Ballerina is a cloud-native programming language whose syntax and run-time address the difficult problems of integration.

What is a client endpoint

Ballerina uses client endpoints to connect to external systems. With the use of an endpoint, it handles security and makes the end user’s life easier by avoiding the external API behavior. Simply, this is a wrapper of external API.

What is securely invoking

Almost all the client endpoints are secured with different kind of authentication schemes like Basic, HMAC, OAuth 1.0, OAuth 2.0, etc. Some endpoints even support multiple authentication schemes. Simply, securely invoking means how we can connect to those endpoints with the required authentication schemes.


Before starting, you have to setup your machine with Ballerina. Please refer to Ballerina’s Getting Started Guide.

Once you have successfully installed Ballerina, execute ballerina-v command to ensure it works. This should display the Ballerina version you installed.

Let’s Start

The Ballerina HTTP Client Endpoint has a new type called AuthConfig which is implemented for securely invoking an HTTP endpoint. Hence, you do not need to worry about the authentication headers of your HTTP request.

public type AuthConfig {
AuthScheme scheme,
string username,
string password,
string accessToken,
string refreshToken,
string refreshUrl,
string consumerKey,
string consumerSecret,
string tokenUrl,
string clientId,
string clientSecret,

The above implementation, currently you can securely invoke an HTTP client endpoint with following authentication schemes.

  1. Basic authentication
  2. OAuth 2.0 authentication
  3. JWT authentication

Basic Authentication

This is the most simple way to deal with authentication. Here we use a special HTTP header where we add base64 encoded value of ‘username:password’ as a part of the header value.

GET / HTTP/1.1
Authorization: Basic YmF0bRFuOmhdG1hbkAxNjN==

Without worrying about those you have to just pass your username and password mentioning scheme as ‘http:BASIC_AUTH’. It is simple as that in Ballerina.

Sample for basic authentication

OAuth 2.0 Authentication

This is a somewhat complex but highly secured way to deal with authentication. Here we use a special HTTP header where we just add the bearer token as a part of the header value. It is the same as in bearer token authentication scheme. But the difference is that the access token can be manually revoked or automatically expired after a time period. In order to get a new access token and proceed, there is a special mechanism in OAuth 2.0 workflow.

GET / HTTP/1.1
Authorization: Bearer Uwge6OmhNhObkdG1GeaeAxdJd8Bks3j

Without worrying about those you have to just pass your access token, client id, client secret, refresh token and refresh url mentioning scheme as ‘http:OAUTH2’.

Sample for OAuth 2.0 authentication

JWT Authentication

This is also somewhat complex but a commonly used method to deal with authentication. Without worrying on those you have to set the token, scheme and authToken into runtime context as represented in setJwtTokenToAuthContext() method of following code sample and mentioning scheme as ‘http:JWT_AUTH’ at the endpoint declaration part.

Sample for JWT authentication


You can refer the following .bal file which has a summary of all the authentication schemes mentioned above.

Happy coding with Ballerina !



Chanaka Lakmal
Ballerina Swan Lake Tech Blog

PhD Student in Computer Science at UWaterloo | ex-WSO2 (Associate Technical Lead)