Migrating to the New Experience

We're excited to welcome you to athena's new Developer Portal! Just follow these steps to register on this site and create your app to obtain credentials on our new system.

finger pressing on button
  1. Register

    Typically takes a minute

    Register for your new athenahealth account (note: this is different than your current Mashery login). Your new athenahealth credentials are better secured leveraging Okta, an industry leader in authentication security.

  2. Create your test app

    Typically takes a minute

    Go to the Create an App page, login with your account credentials, and follow the prompts to create your new app. You will want to create this as a Preview / Testing app.

    Once your app has been created, save your new credentials in a secure location.

    Note: The secret will only be displayed once and will need to be reset if you forget them.

    Your credentials will look like this:

    Credentials

     

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Both sets of credentials (the old, Mashery and the new, Apigee) will remain active through the migration period. You will not lose the ability to use your current production credentials (Mashery) until the migration period has closed. As we approach this deadline, additional communication will mention the date credentials will be removed. 

  3. Request token

    Typically takes less than a day

    In our new platform utilizing Apigee, we will be adhering to industry best practices on token requests and have thus implemented a 50 per minute token request rate limit in production. In addition to the limit, please review the new process to make changes to OAuth and receive your new tokens: 

    Preview Environment

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com  Current OAuth: https://api.athenahealth.com/oauthpreview/token
    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com  Replace with: https://api.preview.platform.athenahealth.com/oauth2/v1/token

    In addition to user:password in the authorization header, the new platform will now require you to request a scope. It is important to note that without the correct grant type and scope requested, OAuth requests for access tokens will fail. The following example demonstrates how to successfully get a token for preview (be sure to remove the {} from the command when making the call):

    curl -u {CLIENT_ID}:{CLIENT_SECRET} --data "grant_type=client_credentials&scope=athena/service/Athenanet.MDP.*" https://api.preview.platform.athenahealth.com/oauth2/v1/token

    You should receive a response like the following:

    {"access_token": "bSQeVaRd47Tnof8GWbDZTud9ghLP", "expires_in": "300"}

    Breakdown:

    • access_token - the same as before and to be used as a bearer token in API requests
    • expires_in - represents the lifetime of the token in seconds

    NOTE: Users will be required to adhere to best practices by caching and re-using your token. 

    • The lifespan of the token is 60 minutes, which is the same as it was on the old platform.
    • There will be a 50 per minute rate limit in production and a 5 per minute rate limit in preview on new token requests. 
    • If you exceed this limit, your application will be blocked (429 response) from requesting new tokens for the remainder of the minute.
  4. Update the API base URL and subscription endpoints

    Typically takes less than a day

    Making an API call on the new platform is nearly identical to the way it is currently being done. The only difference is the base domain. See the following example:

    Preview Environment

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com  Current API Path: https://api.athenahealth.com/preview1/{practiceid}
    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com  Replace with: https://api.preview.platform.athenahealth.com/v1/{practiceid}

     

    Curl "https://api.preview.platform.athenahealth.com/v1/195900/ping" -H "Authorization: Bearer {access_token}"

    Note: as part of the migration, our new vendor has a URL limit of 7000 characters including query parameters. For some PUT requests, you may need to move your input parameters to the body of the request as application/x-www-form-urlencoded parameters instead of URL-encoded query parameters.

  5. Test your app

    We recommend testing your app and its connectivity using context ID 195900, as you are immediately granted access to that space. 

    To expedite the onboarding process, you can link your current preview settings (e.g., tablespace connections, permissions, subscriptions) in the 'Migration' tab of your application. 

    By clicking 'Connect', you will be prompted to input your Mashery Client ID and a valid Mashery token. Once you have hit 'Link App', it will then sync that information. Please note that this will only work for an unused preview application.

    Before requesting to move into production, ensure that you have completed the following:

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Updated your token request code based on the items in Step 3

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Altered the base API URLs as noted in Step 4

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Tested your configuration process and workflows

    Note: If you have any issues with the request process, please reach out via our standard support processes with the specific errors or examples as applicable.

  6. Indicate production readiness

    Once you have completed testing, you will be able to request your production credentials via the 'Migration' tab on your preview application. 

    When you hit 'Request' you will be asked for the following:

    • Application Name
    • Current key used in production
    • e-mail used for the new developer portal
    • Your new preview key

    Upon clicking 'Create' your production app will be created with your current production settings in place (e.g., practice connections, permissions, subscriptions). Your Client ID and Secret will also be displayed to you at this time. 

    Note

    • The secret will only be displayed once and will need to be reset if you forget it. 
    • If you have any issues with the request process, please reach out via our standard support processes with the specific errors or examples as applicable.

     

  7. Go live in production

    Typically takes 2-4 hours

    Logging into the Console, you will see the new application production_application_name. Click 'View App' for the Production app and then reset the secret. 

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com You will then need to write your new Client ID and Secret in your production code.

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com  Current OAuth: https://api.athenahealth.com/oauth/token
    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com  Replace with: https://api.platform.athenahealth.com/oauth2/v1/token

    Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com Font Awesome fontawesome.com You will also need to change the base URLs to point at production.

      Current API Path: https://api.athenahealth.com/v1/{practiceid}
      Replace with: https://api.platform.athenahealth.com/v1/{practiceid}

    Once completed, you are live in the new production environment! You should start migrating your API call traffic from the current platform to the new Apigee platform as you're able.

Frequently Asked Questions

  • Can we migrate our clients on a client by client basis? Will my current credentials stay active?

    Yes. During this migration, you will have access to both the Mashery and Apigee credentials. Outside of making us aware that your plan is to transition in a phased fashion, the work to ensure you have all your clients covered via calling the old or new platform, is up to you.

  • How long will this take?

    We’ve added in rough guidance on timelines for each step. For code changes, testing, and scheduling go live, these times may move quicker. Ultimately, we can move as quickly as you’re able with testing and making changes.

  • How do I track my current daily quotas?

    There are response headers returned upon each request for your convenience.  The headers may represent different meanings depending on the request context.  Below is a table detailing the differences. 

    Request Context 

    Header 

    Description 

    OAuth Request 

    X-RateLimit-Limit 

    The limit of OAuth requests the app can make within a period of one minute. 

    OAuth Request 

    X-RateLimit-Remaining 

    The number of remaining counts the OAuth API can be used within the minute before being rate-limited.  This count resets at the top of every minute. 

    API Request 

    X-RateLimit-Limit 

    The limit of API requests you can make in a period of one day. 

    API Request 

    X-RateLimit-Remaining 

    The number of remaining counts the normal API can be used before being capped.  This count resets at midnight GMT. 

    API Request 

    X-Request-Id 

    An identifier associated with this request. 

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit

On this Page