Authentication

By leveraging OAuth 2.0, developers can empower their applications to seamlessly interact with Alvys' API on behalf of their users. This guide outlines the authentication process and provides detailed instructions on obtaining access tokens through direct application integration.

📘

Getting API Access

• Existing Alvys customers can obtain API access by contacting their account representative.
• Independent Software Vendors (ISV) should contact the Alvys Partnership team.

Obtain OAuth Credentials

Create Client Application

To begin, create a new application from the Alvys Admin page. This will allow you to generate a client_id and client_secret.

• client_id: The unique identifier assigned to this application or caller.
• client_secret: A confidential token also provided by Alvys upon application registration.

Construct Authorization Request

Your application must redirect the user to Alvys's authorization endpoint to initiate the OAuth 2.0 authorization flow:

https://integrations.alvys.com/api/p/authentication/{tenant_id}/token

Construct a URL with the following parameters in the request body:

1. client_id: The unique identifier assigned to your application by Alvys.
2. client_secret: The confidential token provided by Alvys upon application registration.
3. tenant_id: The tenant ID for which the client application was registered.
4. grant_type: The type of grant flow to use. Must be client_credentials

Example curl request to obtain the access token:

curl --request POST \
     --url 'https://integrations.alvys.com/api/authentication/{TENANT_ID}/token' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data 'client_id={CLIENT_ID}' \
     --data 'client_secret={CLIENT_SECRET}' \

Make sure to replace the{CLIENT_ID}, {CLIENT_SECRET}, {TENANT_ID} with the provided credentials. Secure and save them for later steps.

This request will generate a Bearer (access) Token, which is used to authenticate requests against the Alvys API.

⚠️ Remember that your Credentials and Tokens are a secret! Do not share them with others or expose them in any client-side code (browsers, apps). Production requests must be routed through your own backend server where your Credentials and Tokens can be securely loaded from an environment variable or key management service.

Using the Access Token

Use the access token to authenticate API requests to the Alvys platform. Include the token in the Authorization header as a Bearer token.

Example curl request to access a resource using the access token:

curl --request GET \
  --url 'https://integration.alvys.com/v1/me' \
  --header 'Authorization: Bearer ACCESS_TOKEN'

Troubleshooting

Follow the above steps to ensure your authentication process is set up correctly. Try the following if you encounter any issues:

✅ Check Request Parameters: Ensure that all required parameters are correctly specified in your request. Verify that the client_id and client_secret are accurate.
✅ Application Provisioned: Double-check that you have specified the correct callback URLs or redirect URIs.