Authorization
Getting started with OAuth and Oyatel
The Oyatel API relies entirely on the latest OAuth 2 protocol that is fast becoming the industry standard for API authorization, and is already being used by Facebook and a host of other sites and web apps.
The use of OAuth enables third party developers to build applications that can fetch data on behalf of Oyatel users without the need to obtain their usernames and passwords.
There are some good explanations as to why we chose OAuth 2 over the 1a version over at http://www.sociallipstick.com/?p=239.
How to obtain an access token
In order to make API requests on a user’s behalf, you’ll need to obtain an access token. To do so, you’ll redirect the user to Oyatel to authorize your app. If the user authorizes your app, they are redirected back to your app with a code your app can use to obtain an access token.
Client profiles
At a high level, using OAuth 2 entails getting an access token for a Oyatel user via a redirect to Oyatel. OAuth 2 supports a wide range of client types by providing a rich and extensible framework for establishing authorization and exchanging it for an access token. The Oyatel API is designed to accommodate three client types: web servers, user-agents and native applications.
(Click on the client-type matching your application to get more details about the steps involved)
WebServer
In greater detail, the Web Server flow goes like this:
- Redirect the user to https://oauth.oyatel.com/oauth/authorize. You must pass your app’s Client ID using the client_id parameter. You must also pass a redirect_uri parameter in the query string to let Oyatel know where to redirect the user to once they have authorized or denied your app. This URL must match the callback URL you registered your app with. Additionally, you must specify the response_type with a value of code.Here’s an example (line breaks are for display purposes only):
https://oauth.oyatel.com/oauth/authorize? response_type=code& client_id=[YOUR_CLIENT_ID]& redirect_uri=http://example.com/oauth_redirect
- After the user authorizes or denies access to your app, Oyatel will redirect them to the callback URL you registered the app with. The request will either contain an authorization
code
or an error indicating the user did not authorize your app. Here’s an example, assuming theredirect_uri
of http://example.com/oauth_redirect:http://example.com/oauth_redirect?code=1234abcd
- If the user authorized your app, the above request will be returned with an authorization code. You should then make a POST request to https://oauth.oyatel.com/oauth/token, passing the following parameters:
grant_type
– should use authorization_code as the valueclient_id
– the API key for your appclient_secret
– the secret key for your appcode
– the authorization code from the redirect to your app from Oyatelredirect_uri
– the callback URL for your app
Here’s an example (line breaks are for display purposes only):
POST /oauth/token HTTP/1.1 Host: oauth.oyatel.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& client_id=[YOUR_CLIENT_ID]& client_secret=[YOUR_CLIENT_SECRET]& redirect_uri=http://example.com/oauth_redirect& code=[CODE]
If these parameters all match what Oyatel has registered for your app, an access token will be issued and returned in the response, along with these parameters:
access_token
– access token used to make API requests on behalf of the userrefresh_token
– a refresh token used to obtain new access tokens once they expireexpires_in
– The duration in seconds of the access token lifetime. Currently set to a year.
Here’s an example of the JSON response (line breaks are for display purposes only):
{ "access_token": "[ACCESS_TOKEN]", "refresh_token": "[REFRESH_TOKEN]", "expires_in": 1209600 }
All requests to /oauth/* must be over HTTPS.
User-Agent
Unlike other profiles in which the client makes separate requests for end-user authorization and access token, the client receives the access token as a result of the end-user authorization request in the form of an HTTP redirection. The client requests the authorization server to redirect the user-agent to another web server or local resource accessible to the user-agent which is capable of extracting the access token from the response and passing it to the client.
This user-agent profile does not utilize the client secret since the client executables reside on the end-user’s computer or device which makes the client secret accessible and exploitable. Because the access token is encoded into the redirection URI, it may be exposed to the end-user and other applications residing on the computer or device.
In greater detail, the User-Agent flow goes like this:
- Redirect the user to
https://oauth.oyatel.com/oauth/new
. You must pass your app’s Client ID using theclient_id
parameter. You must also pass aredirect_uri
parameter in the query string to let Oyatel know where to redirect the user to once they have authorized or denied your app. This URL must match the callback URL you registered your app with. Additionally, you must specify theresponse_type
with a value oftoken
.Here’s an example (line breaks are for display purposes only):https://oauth.oyatel.com/oauth/authorize? response_type=token& client_id=[YOUR_CLIENT_ID]& redirect_uri=http://example.com/oauth_redirect
- After the user authorizes or denies access to your app, Oyatel will redirect them to the callback URL you registered the app with. The request will either contain an authorization code within the URI fragment, or an error indicating the user did not authorize your app.
Here’s an example, assuming the redirect_uri of http://example.com/oauth_redirect:
http://example.com/oauth_redirect#access_token=[ACCESS_TOKEN]&expires_in=[EXPIRES_IN_SECONDS]
A
refresh_token
is not used in this User-Agent profile. To obtain a newaccess_token
after it expires, just repeat this process
Native/Desktop Applications
Native application clients can be implemented in different ways based on their requirements and desired end-user experience. Native application clients can:
- Utilize the end-user authorization endpoint as described in the User-Agent section by launching an external user-agent. The client can capture the response by providing a redirection URI with a custom URI scheme (registered with the operating system to invoke the client application), or by providing a redirection URI pointing to a server-hosted resource under the client’s control which makes the response available to the client (e.g. using the window title or other locations accessible from outside the user-agent).
- Utilize the end-user authorization endpoint as described in the User-Agent section by using an embedded user-agent. The client obtains the response by directly communicating with the embedded user-agent.
Additional Resources
If you want to get more into the details, you can also check out these external pages for OAuth information: