Authentication

Metwit implements OAuth 2.0 standard (RFC 6749) to authenticate clients and guarantee the privacy of user data.

API calls require a valid access token. An access token is a string obtained through an authentication process, as described by OAuth 2.0. When you have an access token you can use it with your HTTP calls to Metwit API in the Authorization header like this:

Authorization: Bearer access_token_string
                

Registration

Prior to using Metwit API you need to register an application on Metwit. If you are not registered as a Metwit users you can do it now here. Then you can register a new application here and obtain a client id and a client secret.

The client id is a public identifier assigned to your application, while the client secret acts as a password for your application, so be careful with it. Metwit will need these credentials during the authentication process.

Authorization

Metwit provides a number of different methods to obtain an access token, depending on the specific needs of application developer.

• If you need your application to act on behalf of an user, you need to get authorization from the user through Metwit authorization dialogs. At the end of the process you will get an access token authorized to access user data and, more importantly, to post new weather reports to Metwit.
• If your applications only want to access weather data and doesn’t need authorization from an user, it can get an access token using only its client credentials. Both methods are described below.
• While authorization dialogs are the recommended way to obtain an authorized access token for an user, it can sometimes be inconvenient to have the end user go through a web browser. For this reason Metwit authorizes certain clients to use an additional method to get an access token if you have username and password of the user’s account on Metwit. If you think your application needs authorization to use this please send an email to support@metwit.com requesting “Access to password authentication” and explaining why you need it.

Authorization dialogs

Authorization dialogs are the secure way Metwit users can grant permission to third parties through a web browser. All you need is to let the users visit this URL:

http://metwit.com/oauth/authorize/?client_id=<client_id>&response_type=code&redirect_uri=&scope=<scope>&state=<state>
                

Replace the parameters with the values that apply to your application as follows.

client_id is the client id you got when you registered the application (check your Developer Dashboard).
redirect_uri is the URI the end user will be redirected to at the end of the procedure with the authorization code needed to complete the authentication process.
scope is a space separated list of the permissions the application is requiring on the user's resources. Currently, the only scope available is 'post_metag'. It allows an app to post metags in behalf of the users.
state is an arbitrary string that will be returned verbatim together with the authorization code.
http://example.com/metwit_authorize?state=123456&code=authorization_code

You can then exchange authorization_code with a valid access token at the token endpoint. Read on the "Obtaining access" section for details.

Implicit authorization

When your application runs as a JavaScript within a browser it doesn't make much sense to go through the full authorization code flow, so a simplified flow is provided that requires one less step for the developer to implement.
Just change the response_type parameter of the dialog URL to "token" instead of "code".
Following the previous example, after granting authorization the user will be redirected to:

http://example.com/metwit_authorize#state=123456&access_token=my_token&expires_in=3600
                

Note that the response is now part of the URI #fragment, not the ?query_string. Also note that since an access token expires after its validity period and this method doesn’t give you an access token, you will need to perform authorization again every time the token expires.

Obtaining access

Whatever the type of your grant is, when you need an access token you can post a request to the token endpoint at https://api.metwit.com/token/.
Encode the parameters of your request as detailed below in the request body as application/www-form-urlencoded.

Unless your application is a public client (a mobile application, a native application, a web JavaScript application or any kind of code deployed on the user site that is unable to guarantee application secrets), any call to the token endpoint must be authenticated with your client id and client secret. Use HTTP Basic authentication scheme like this:

Authorization: Basic base64(client_id:client_secret)
                

Don't worry about authentication if you are building a public client. In that case it is recommended to just use authorization dialogs.

Authorization code

Unless you followed the implicit flow, if your end users has gone through the authorization dialogs process you will have an authorization code by now. Exchange it with an access token:

POST /token/
Content-type: application/www-form-urlencoded

grant_type=authorization_code&
code=<code>&
redirect_uri=<redirect_uri>&
client_id=<client_id>
                

Parameters:
code is the authorization code as returned by the dialog procedure
redirect_uri is the same redirect_uri as used in the dialog
client_id is the client id you got when you registered the application. Optional if the request is authenticated

Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token": "the_access_token",
   "token_type": "bearer",
   "expires_in": 3600,
   "refresh_token":"the_refresh_token",
}
                

Client credentials

This is the simplest method when you just need to know the weather and don't need to get authorization from an user.
All is needed is to authenticate the request to the server as explained before.

POST /token/
Content-type: application/www-form-urlencoded
Authorization: Basic eW91cmNsaWVudF9pZDpaS1U5bUxGZHBJS2M5VHlNaU9zZ1Bt

grant_type=client_credentials
                

Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token": "the_access_token",
   "token_type": "bearer",
   "expires_in": 3600,
   "refresh_token":"the_refresh_token",
}
                

Username & Password

This method is only accessible if your application is authorized by Metwit (see "Authorization" above for details).
You provide the username and the password of a Metwit user account and you get an access token. As requesting a user password requires a high level of trust, your application must never store nor cache the user password, in any form (not even encrypted), and it must never send the password on the network. After using the credentials the client must discard them.

POST /token/
Content-type: application/www-form-urlencoded
Authorization: Basic eW91cmNsaWVudF9pZDpaS1U5bUxGZHBJS2M5VHlNaU9zZ1Bt

grant_type=password&
username=<username>&
password=<password>&
scope=<scope>
                

Parameters:
username is the Metwit user account username or email address
password is the Metwit user account password
scope is a space separated list of the permissions the application is requiring on the user’s resources.

Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "the_access_token",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token":"the_refresh_token",
}
                

Access token expiration and refresh tokens

Every time a client gets an access token it is also provided its duration in seconds in the expires_in parameter.
After this time trying to access resources with the token will result in an unauthorized (HTTP 401) error.
To avoid having to go through the authorization process every time, the token endpoint will also issue a long lasting token, called a refresh token. Every time an access token expires, clients can request a new one using just the refresh token.

POST /token/
Content-type: application/www-form-urlencoded
Authorization: Basic eW91cmNsaWVudF9pZDpaS1U5bUxGZHBJS2M5VHlNaU9zZ1Bt

grant_type=refresh_token&
refresh_token=<refresh_token>&
scope=<scope>
                

Parameters:

refresh_token is the previously obtained refresh token
scope is a space separated list of the permissions the application is requiring on the user's resources. This is optional and only required if you want to restrict access. You can’t specify a broader scope than the original request.

Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token": "the_access_token",
   "token_type": "bearer",
   "expires_in": 3600,
   "refresh_token":"the_refresh_token",
}