Practices and medical groups business challenges
Availity API Gateway Migration

Migrate to your new keys now; existing keys to expire Oct. 13

Availity has quickly outgrown the capabilities of the current API gateway and will be retiring its existing developer portal. While you will still have access to the retiring developer site, you should migrate now to allow time for testing before your legacy API key expires.

Our new portal and key provisioning improves security using enhanced access tokens, demo endpoint enhancements, and new coding samples for our health care APIs. As we move to this new platform, you will notice changes to the API Authentication section of our documentation at migrate-developer.availity.com. You will also have access to more coding samples to see how the APIs work and the results you can expect.

Migration Steps – Don’t Delay
  1. Get Started Here
    • Create New Account. You can use your existing email and login, but you’ll need to create a new password.
    • Log in to register an application.
    • Click the Apps tab, then Create new App in the upper right corner of the page. A notification will be sent to Availity API Support. Once verified, your application will be approved. Note: If you register with a different email, Availity may contact you for verification before approving your application.

      IMPORTANT:
      Security best practices restrict you from seeing your client secret after the application is created. Availity does not have access to your client secret and cannot reset it for you. You should immediately record your client secret when you create it.

      Note: You’ll be able to reset the client secret if you forget it using the Reset button on the Client Secret page. Resetting your client secret changes existing application credentials.

    • Subscribe to the Demo Plan for access to mock data responses, and to the Standard Plan for live data. Each app can only be associated to one plan subscription at a time. Your standard key will be available after establishing pricing and signing a contract. If you already have a contract in place, you can get a standard key today.
    • Migrate your existing applications:
      • Replace existing API keys with new client ID values (GUID—your globally unique identifier).
      • Replace existing API secret values with new client secret values associated with your new client ID.
        • Using the authentication endpoint https://api.availity.com/v1/token, add your newly required POST method payload parameters:
          • client_id={API KEY}
          • client_secret={API SECRET}
          • scope=hipaa
      • Start testing.

    Token Endpoint:
    https://api.availity.com/v1/token

    Curl Example:
    curl -i -k -X POST -d 'grant_type=client_credentials&client_id={API KEY}&client_secret={API SECRET}&scope=hipaa' 'https://api.availity.com/v1/token'

    NOTE About Content-Type Response Header: Empty string payloads will no longer contain a Content-Type header

    Example:
    Note:
    Content-Type Header is not returned when content-length = 0

    HTTP/1.1 202 Accepted
    Connection: Keep-Alive
    Transfer-Encoding: chunked
    Date: Mon, 03 Jul 2017 16:04:32 GMT
    X-Global-Transaction-ID: 1561139055
    Cache-Control: private,no-store,max-age=0,must-revalidate
    Location: https://api.availity.com/v1/dental-claims/-12345678
    X-api-id: 716354b5-a350-4be8-9c8b-dc88a1a69c36
    X-Session-ID: 716354b5-a350-4be8-9c8b-dc88a1a69c36
    X-Status-Message: We are processing your request.
    X-planid: healthcare-hipaa-transactions:1.0.0:standard
    X-planname: standard>
    X-RateLimit-Limit: name=throttle,10; name=quota,10000;X-RateLimit-Remaining: name=throttle,9; name=quota,9997;

    Note: Content-Type Header is returned when content-length > 0

    HTTP/1.1 200 OK
    Connection: Keep-Alive
    Transfer-Encoding: chunked
    Content-Type: application/json
    Date: Mon, 03 Jul 2017 16:06:17 GMT
    X-Global-Transaction-ID: 1561195199
    User-Agent: IBM-APIConnect/5.0
    Cache-Control: private,no-store,max-age=0,must-revalidate
    X-api-id: 0ec7af44-2573-486c-9f0a-f5e2d4b60ba1
    X-Session-ID: 0ec7af44-2573-486c-9f0a-f5e2d4b60ba1
    X-planid: healthcare-hipaa-transactions:1.0.0:standard
    X-planname: standard
    X-client-app-id: 0fa0144b-1371-4479-83b6-2dd8d83ae16a
    X-Incoming-Forwarded-For: api.availity.com
    X-RateLimit-Limit: name=throttle,10; name=quota,10000;
    X-RateLimit-Remaining: name=throttle,9; name=quota,9996;
    {
    totalCount": 5,
    "count": 5,
    "offset": 0,
    "limit": 50,
    "links": {
    "self": {
    href": "https://api.availity.com/ v1/coverages"
    }
    }…

    Note About API Endpoints:
    To minimize the number of changes for existing customers, the /availity URI path segment will automatically be added when making API requests.

    This Example:
    curl -i -k -X POST -d
    'grant_type=client_credentials&client_id={API
    KEY}&client_secret={API SECRET}&scope=hipaa'
    'https://api.availity.com/v1/token'

    Works the same as this example:
    curl -i -k -X POST -d 'grant_type=client_credentials&client_id={API KEY}&client_secret={API SECRET}&scope=hipaa' 'https://api.availity.com/availity/v1/token'

    Q: Is the Availity Developer Portal URL changing?

    A: No. https://developer.availity.com is still the landing page for the Availity Developer Portal. As of August 14 you’ll be able to obtain and provision your new key at that site. Use the New keys button on the entry page of the site.

    If you are unable to log in, follow the migration steps outlined above.

    Q: Will I still have access to the retiring developer portal?

    A: Yes, until October 13, 2017 you will have limited access to your API keys and analytics.  Select the Legacy keys button on developer.availity.com.

    You can still log in using your existing credentials. No new API keys will be provisioned from the retiring site.

    Q: Is oAuth2 still supported?

    A: Yes, scope is now required.
    You also need to add your newly required POST method payload parameters:

    client_id={API KEY}
    client_secret={API SECRET} 
    scope=hipaa

    Your specification should reflect the following sample:

    Curl Example:
    curl -i -k -X POST -d 'grant_type=client_credentials&client_id={API KEY}&client_secret={API SECRET}&scope=hipaa''https://api.availity.com/v1/token'

    Q: Are there any changes related to the oAuth2 specification?

    A: Yes, scope is now required.

    Q: What is scope?

    A: Scope simply provides a means for more granular access privileges. There is only one scope defined today. scope=hipaa
    Learn more about access token scope here.

    Q: Is digest (MD5 and SHA256) still supported?

    A: No. For security reasons Availity no longer stores client secrets in plain text format. Digest authentication is no longer supported.

    Q: Do demo endpoints require oAuth2 Authentication?

    A: Yes. Availity demo endpoints now support oAuth2 authentication, just as live data endpoints do.

    Q: Is the access token length changing?

    A: Yes. You will notice the access token length has changed, as longer tokens are more secure.
    This example shows the relative lengths of the legacy and new access tokens:

    Legacy format:

    {"access_token":"abpxr2nrztan2ngsuw552uf7","token_type": "bearer","expires_in": 300}

    New format:

    { "token_type":"bearer", "access_token": "AAEkZGI1ZjRhYzgtYWViNy00NmRmLWE0YjYtNDg5NTliZDI0NTc2lzhhnd4OH4kny-DbfYL_WdgtC4gnsvmdkw6w3N_Q_EggoC-nqL-ck2o5CZcHxic5lQSiEZLK8wO0f5yHMvHzWo-k5b9VF_4pbhm1Z4ox_Q1-j5oR_HceA-V8vXYTIWBgyOHiPXMHmQvFMgU8B8rhGw", "expires_in":300, "scope":"hipaa" }

    Learn more about oAuth2 Authorization Framework.

     

    Availity has set the demo endpoints to be the same as production endpoints because many developers have asked for the change.

    Q: Do demo endpoints require authentication?

    A: Yes. Demo endpoints now require oAuth2 authentication exactly the same as live data endpoints. You will have a separate client ID and secret value for the demo endpoint. See step two in the migration instructions to register an application.

    Q: Is the demo endpoint changing?

    A: Yes. The demo endpoint will be same as the live endpoint. There will no longer be a separate URL as a demo endpoint.

    Q: How will I know I am requesting the demo response?

    A: You can confirm you've received a mock response by inspecting the response headers. You should see the following header:
    X-Api-Mock-Response: true

    Q: Is the header changing for the X-Api-Mock-Scenario-ID?

    A: Yes — you can still choose which demo response you want by sending a header with your request. The name of the header is X-Api-Mock-Scenario-ID and the value is the ID of the response scenario you want. You can find supported response scenarios in the documentation of each endpoint.

    Learn more about demo endpoints: https://migrate-developer.availity.com/partner/documentation#demo-endpoints