API authentication

Every request to the Infobip API needs two things: the Base URL of your account, and credentials in the Authorization header. Infobip supports four authentication methods: API keys, OAuth 2.0, IBSSO tokens, and HTTP Basic authentication. Use an API key unless your tech stack or security requirements call for another method.

Authentication proves who is calling. What the call is allowed to do depends on the scopes of your credentials: see Authorization and scopes. If a request fails with 401 Unauthorized, see Authentication errors.

Base URL

Every API request must include the Base URL unique to your account, in the format xxxxx.api.infobip.com. To find yours, log in to your account. The Base URL is shown on your homepage and on the API keys page of the web interface, and the API docs display it in every endpoint example.

Choose an authentication method

Whichever method you use, send requests over an encrypted TLS connection. See REST API traffic encryption.

The following table compares the methods, from most to least recommended, across security, complexity, session lifetime, and ideal use cases.

To troubleshoot authentication issues, see Authentication errors and Handling errors, or contact Support.

API key authentication

An API key is an access token that your application provides when making API calls. It is a simple way to secure access, which makes it the most popular authentication method for REST APIs. Send the key as a request header, using the App prefix: Authorization: App {your-api-key}. Avoid sending it in the query string, where it can leak into server logs and browser history.

Self-signup accounts are automatically assigned an API key after you create an account. Managed accounts do not receive an API key automatically, so generate one before you make your first API call.

• You can revoke keys at any time, which is useful when separating API access rights across multiple applications or use cases.
• API keys expire on the date you set. If you create a key through the API without an expiry date, it expires 1 year after creation.
• Rotate API keys regularly, and immediately if a key is exposed. See Security best practices.

How to use API keys [#how-to-use-api-keys-api-key-authentication]

1. Get an API key. A self-signup account comes with an API key. To create more, or on other accounts, generate one on the Infobip API key management page (Developer Tools > API Keys). You can also use the Create API key endpoint. The API key endpoints do not accept an API key, so authenticate those calls with Basic authentication, OAuth 2.0, or an IBSSO token.
2. Assign the scopes your integration needs to the key. See Authorization and scopes for available scopes and how to assign them.
3. Include App and the key in the Authorization header on every API request: Authorization: App {your-api-key}.

Send a request with an HTTP client [#use-http-client]

The following examples send an SMS message with the Send SMS endpoint, authenticated with an API key. Replace {baseUrl} and {apiKey} with your own values.

Send a request with an API client library [#use-an-api-client-library-api-key-authentication]

The API client libraries support API key authentication. Provide your Base URL and API key when you create the client. The library adds the App prefix to the Authorization header for you.

OAuth 2.0 authentication

OAuth 2.0 is the most secure authentication option and an industry standard, defined in RFC 6749(opens in new tab). You get a short-lived access token from the Create OAuth2 token endpoint and send it with each request.

• The access token expires within the time limit provided in seconds in the response.
• Infobip acts as both a resource and an authorization server.
• You must create a new token after the token expires. There is no automatic token retrieval.

How to use OAuth 2.0 authentication [#how-to-use-oauth-20-authentication-oauth-20-authentication]

1. Call Create OAuth2 token to get the access token and its expiration time.
2. Include Bearer and the token in the Authorization header for all subsequent calls: Authorization: Bearer {access_token}.

Get an OAuth 2.0 token [#get-an-oauth-20-token-oauth-20-authentication]

The following examples call the Create OAuth2 token endpoint and read the token from the response. Use your Infobip username as client_id and your password as client_secret. The expires_in field in the response contains the token lifetime in seconds.

Send a request with an OAuth 2.0 token [#send-a-request-with-an-oauth-20-token-oauth-20-authentication]

The following examples assume you have completed step 1 and have an accessToken value. The request is the same as for API key authentication, but uses Bearer instead of App in the header.

IBSSO token authentication

IBSSO (Infobip single sign-on) tokens are session-based, meaning tokens expire after a short time. That makes this method more secure, but also requires more maintenance to keep authentication active. This method is typically used in single sign-on scenarios.

• All API requests are authenticated with a session token.
• By default, IBSSO tokens expire after roughly 60 minutes of inactivity.
• If you want to create a new token before the previous one expires, you must first destroy the session.
• To make a session shorter than 60 minutes, destroy it when you no longer need it.

How to use IBSSO tokens [#how-to-use-ibsso-tokens-ibsso-token-authentication]

1. Call Create session and take the token from the response.
2. Include IBSSO and the token in the Authorization header: Authorization: IBSSO {token}.
3. (Optional) Call Destroy session to end the session before it expires.

Get an IBSSO token [#get-an-ibsso-token-ibsso-token-authentication]

The following examples call the Create session endpoint and read the token from the response.

Send a request with an IBSSO token [#send-a-request-with-an-ibsso-token-ibsso-token-authentication]

This request is almost identical to API key authentication. Instead of App, you use IBSSO in the header.

Basic authentication

Basic authentication works by sending a username and a password in every API request, Base64-encoded and passed with the Basic prefix: Authorization: Basic {base64-encoded-credentials}. Use it when an API key is not available. For example, the endpoints that create and manage API keys do not accept an API key.

• Built into the HTTP protocol itself. See HTTP authentication(opens in new tab) on MDN.
• Credentials encoded in Base64 format and separated by a colon.
• Encoded credentials added to the header after Basic.

Unlike API keys, where you explicitly assign scopes during key creation, Basic authentication does not use scopes directly. Instead, the roles assigned to the user whose credentials you are using determine the scopes available to a Basic authentication request. For the role-to-scope mapping, see User roles and API scopes in API scopes reference.

How to use Basic authentication [#how-to-use-basic-authentication-basic-authentication]

Basic authentication must be enabled for your user. See API access in Manage users.

1. Concatenate your username and password separated by a colon: username:password.
2. Encode the result in Base64.
3. Include Basic and the encoded string in the Authorization header: Authorization: Basic {base64-encoded-credentials}.

Send a request with Basic authentication [#send-a-request-with-basic-authentication-basic-authentication]

The following examples encode the credentials and send them in the Authorization header. The curl example uses already-encoded credentials.

Authentication errors

You receive the 401 Unauthorized HTTP status code when credentials are missing or incorrect. This applies to all four authentication methods.

Some endpoints can return a previous version of the error:

Library exceptions [#library-exceptions-authentication-errors]

When you use an API client library, an error response such as 401 Unauthorized throws an ApiException. The following examples read the status code and response body from the exception. The smsApi and smsRequest objects come from Use an API client library.