The first step in getting access to data via Akoya is to send your user to an Akoya authorization URL. Akoya will direct your user through their appropriate data provider's login and account authorization process and on success, will redirect them back to a URL you specify with an authorization code.
The request URL
Include the following parameters in your URL's path:
| URL path parameter | Description |
|---|---|
| Base URL | Sandbox authorization URL : https://sandbox-idp.ddp.akoya.com/auth |
| connector | The Akoya identifier for the data provider your user will be logging in to. Akoya takes this identifier and directs the user through the appropriate FI's login flow. For sandbox testing purposes, use mikomo |
| client_id | Your application's client ID from Akoya. |
| redirect_uri | The redirect URI that you registered with Akoya for that client ID. Akoya will validate that the redirect URI exactly matches the one registered, to prevent malicious redirects. |
| response_type | The OAuth 2 grant type being requested. Akoya only accepts code, indicating that the application expects to receive an authorization code if successful. |
| scope | Space separated values to request levels of access. For example: openid offline_access. |
| state | Any random string generated by your application. Akoya will include this state value back to your application upon completion of the authorization request for you to validate, in order to prevent CSRF attacks. We recommend the value of state being at least 8 characters long. |
This is a browser redirect that will return an authorization code and not an API response.
Once your app receives the authorization code, you can present the code to Akoya in exchange for an ID token.
Note
Each authorization grant code expires in 5 minutes.
For more on the authorization request process and tokens used in the Akoya Data Access Network, see: "Token flow".
Authorization URL
Use the authorization URL in a browser window, complete the consent flow, and get the authorization code.
Build your own URL
There are minor differences between sandbox and production authorization URLs, as detailed below:
| Sandbox parameter values | Production parameter values |
|---|---|
https://sandbox-idp.ddp.akoya.com/auth? | https://idp.ddp.akoya.com/auth? |
connector=mikomo& | connector={providerId}& |
client_id={clientId}& | client_id={clientId}& |
response_type=code& | response_type=code& |
redirect_uri={client-redirect-URL}& | redirect_uri={client-redirect-URL}& |
scope=openid&offline_access& | scope=openid&offline_access& |
state={state} | state={state} |
Replace CLIENT_ID in the example below and paste into a browser window.
Note: The sandbox default redirect URI is used in this example. If your app is using https://recipient.ddp.akoya.com/flow/callback you only need to replace your client id.
https://sandbox-idp.ddp.akoya.com/auth?connector=mikomo&client_id=CLIENT_ID&redirect_uri=https://recipient.ddp.akoya.com/flow/callback&response_type=code&scope=openid%20email%20profile%20offline_access&state=appstate
Example success URL:
https://example-app.com/callback?code=fogeqqbz2xi23hvgvlu4ka2kq&state=123abc
https://sandbox-probo.ddp.akoya.com/?url=http://localhost:8081/__akoya-authorize2&error=invalid_scope&error_description=Missing+required+scope%28s%29+%5B%22openid%22%5D.&state=12345
Need help?
Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.
Looking for provider nuance documentation?
All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.
Still stuck?
For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.