In May, we launched the beta Heroku Platform API - making it possible to automate, extend and combine the Heroku platform with other services in a programmatic, self-service way. As of today, OAuth 2.0 support for the Platform API is available in public beta.
With OAuth support, developers building integrations and services that use the Heroku API can provide a much better experience to their users. Instead of requesting full access to user accounts, access requests can be scoped to just the information and control a service needs. Instead of using one API key for all third-party services, users can check and revoke authorizations on a case-by-case basis. And users can manage all of their third-party authorizations within their Heroku dashboard.
API Developers
If you are building a service that uses the Platform API, you should implement OAuth. First, register a client from the account page on Dashboard. You can then incorporate OAuth into your app using OmniAuth, the Heroku Bouncer middleware or another tool of your choice. The Heroku OAuth article has additional details, resources and links to sample apps.
For Heroku Users
With the Platform API, developers can now build awesome services that integrate with Heroku - for example, an iPhone app to monitor apps running on Heroku, or a CI service that can push changes to your apps so your workflow is smoother and more automated. However, these services need access to some or all of your Heroku account to work. OAuth gives you a safe mechanism to control this access. When a service uses OAuth to request access to your account, you will be redirected to id.heroku.com where you can see who is requesting access and the scope of the access requested. Here are the scopes we have implemented so far:
global: Full access to account and to control all apps and resources. Equivalent to API key (but revocable).identity: Read-only access to account-info.readandwrite: Access to read and write info on apps and other resources, except configuration variables. This scope lets you grant access to your apps without necessarily revealing runtime secrets such as database connection strings.read-protectedandwrite-protected: Same as above, but including access to config vars.
Note that the read, write, read-protected and write-protected scopes do not grant access to account identity details such as email address.
Before granting access to a 3rd party service, make sure that you trust that service to access your Heroku account in a way you feel comfortable with. You can see what external services are authorized on the account page on Dashboard or using the authorizations CLI command from the OAuth CLI plugin. You can revoke authorizations at any time using either the dashboard or Heroku CLI.
OAuth gives 3rd parties services safe, granular and revocable access to the power of the Heroku Platform API. We can’t wait to see what new apps and services get built with these technologies.
If you have questions, suggestions or want to show us what you have created, then drop us a line at api-feedback@heroku.com.