An authentication is a tool in Ringba to refresh an authentication token when you're pinging an outside system. If an HTTP endpoint you use in your pixels or ring tree targets requires a dynamic token, you set up an authentication and add it to your pixel or ring tree target. The authentication refreshes the token so Ringba can successfully communicate with the outside system.

This article contains the following sections:

• Authentications Screen
• Create an Authentication
• Authentications FAQ

Authentications Screen

You set up your authentications by navigating to Integrations > Authentications. 

Here you can set up an authentication record for each system you integrate with. When you navigate to this page, you see a list of all your existing authentications. On this screen, you can perform the following actions:

• Click the Create Authentication button at the top to create a new authentication. See the Create an Authentication procedure later in this article.
• Use the Search box to find a particular authentication in the list
• Click the gear icon beside the Search box to change the columns you see in the list
• Click the header of any column to sort the list by values in that column. Click it again to reverse the sort and click it a third time to remove the sort.
• Click the name of an authentication or the edit button in the Actions column to expand the fields for that authentication.
• Click the delete icon in the Actions column to delete the authentication.
• Click the validate icon in the Actions column to check that the authentication is successfully returning a token as configured.

Create an Authentication

Use the following steps to create an authentication:

1. Navigate to Integrations > Authentications and click the Create Authentication button. 
2. Complete the fields that appear in the first section:
   • Name: Enter a name for the authentication.
   • URL: Enter the URL to ping to generate the authentication token. 
     Tip: Use the Token button on the right side of the field to add URL parameters.
   • Headers: Use the key and value fields to add any additional headers you need to include in the request. You can add more than one header. Click the Add button after each header you enter.
   • Method: Select the HTTP method to use in the request to generate the authentication token. You can choose GET, POST, PATCH, PUT, or DELETE.
   • Content Type: Select the content type of the request body. You can choose application/json, application/xml, application/x-www-form-urlencoded, or text/plain.
   • Body: Enter the body content of the authentication request.
   • Request Timeout (ms): Enter the maximum number of milliseconds to wait for an authentication response.
3. Complete the fields in the Token Usage section:
   • Header Parameter: Enter the header name to use to authenticate subsequent requests. If you leave this field blank, Ringba uses Authorization by default.
   • Default Token Type: Enter the default token type (for example, Bearer or Token). Ringba uses this value if the authentication response does not include a token type value.
   • Default Expiration Time(s): Enter the default expiration time in seconds. Ringba uses this value if the authentication response does not include a expiration time value.
4. (Optional) If the authentication response does not use the standard JPath values to contain the token, token type, and expiration time values, then complete the Request Response Parsing section. Otherwise, you should leave these fields blank.  
   • Token Parsing: Only if the token response does not use the access_token JPath value for then token, then you must create one or more parsing steps to define where to find the token. Click the Add Parsing Step button to show Parsing Type and Parsing Expression fields. Use these fields to create one or more parsing steps to map the Token from the authentication response. 
   • Type Parsing: Only if the token response does not use the token_type JPath value for then token type, then you must create one or more parsing steps to define where to find the token type. Click the Add Parsing Step button to show Parsing Type and Parsing Expression fields. Use these fields to create one or more parsing steps to map the token type from the authentication response. 
   • Expiration Parsing: Only if the token response does not use the expires_in JPath value for the expiration time, then you must create one or more parsing steps to define where to find the expiration time. Click the Add Parsing Step button to show the Parsing Type and Parsing Expression fields. Use these fields to create one or more parsing steps to map the expiration type from the authentication response.
5. Click Create the save the authentication.

Add an Authentication to a Pixel

You use tracking pixels to programmatically send information from Ringba to another platform's endpoint. If the endpoint requires a token that expires, you can add an authentication to the pixel to refresh the token.

Once you've created the authentication using the procedure earlier in this article, you can select it in the Authentication field when you edit the pixel:

See the Pixels article for step-by-step instruction on creating a pixel.

Add an Authentication to a Ring Tree Target

A ring tree target (RTT) is the part of a ring tree that represents an entity that can accept a call. Your ring tree pings all eligible RTTs at the same time to identify the highest bidder for the call. If the endpoint you use to ping the RTT requires a token that expires, you can add an authentication to the RTT to refresh the token.

Note: You can only use an authentication for the initial request, not for the confirmation step.

Once you've created the authentication using the procedure earlier in this article, you can select it in the Authentication field in the Request Settings section of the RTT:

See the Ring Tree Target Setup Guide for step-by-step instructions on creating a ring tree target.

Authentications FAQ

Do I need to set up an authentication if the endpoint requires a static token?

No, if the token does not expire, you do not need to create an authentication. You can simply add the token to the header in the pixel or ring tree target.

When should I use the fields in the Request Response Parsing section?

You use the fields in this section to handle cases where the token response doesn’t use the following standard OAuth 2.0 field names:

• access_token
• token_type
• expires_in

Not all APIs return tokens using these field names. Some might use different field names, for example token, authToken, type, or expiry). Some might even nest the values inside objects. Parsing steps let you extract the correct values from custom or complex API responses and map them to what Ringba expects.

However, you should not set up the fields in the Request Response Parsing section if the API response does use the standard field names. 

What should I do if I need help with my authentications?

If you have any questions or need additional help, please reach out to our support team via chat or email at support@ringba.com.=