WebMini API

Authentication

Introduction

There are two ways to authenticate through WebMini API:

Authentication Type Access Ease of Implementation
Personal API Token Grants access to your personal account only. Very easy.
OAuth2 Users can grant your application access to their accounts. Slightly more complex.

Scopes

Scopes let you specify exactly what type of access you need. Scopes limit access for both Personal API Tokens as well as OAuth2 tokens.

Scope Name Description
sitesmaker:read Grants read access to a Sitesmaker account.
sitesmaker Grants read/write access to a Sitesmaker account.
itemplatform:read Grants read access to an Itemplatform account.
itemplatform Grants read/write access to an Itemplatform account.

Personal API Token

For many API usage scenarios, you might only need access to your very own WebMini account. In that case, implementing a complete OAuth authenication process is not needed. Instead, you create a Personal API Token and use it in your application to access the WebMini API.

Obtaining a Personal API Token

  1. Go to the Personal API Tokens page in your user account.
  2. Click on Add Personal API Token.
  3. Enter a brief description for your token and choose the scopes for it.
  4. Once you added the token, you will see a page that tells you your Token Username and your Token Secret. Do not share your Token Secret with anyone as this functions like a password to your account!

Authenticating with a Personal API Token

You can use your Personal API Token to access the WebMini API using HTTP Basic Authentication:

$ curl -i https://my.webmini.com/api/v1/testservice/auth -u token_username
Enter host password for user 'token_username': token_secret

HTTP/1.1 200 OK
...

["auth test"]

OAuth2

OAuth2 is a protocol that lets external applications request authorization to private details in a user’s WebMini account without getting their password. While a Personal API Token (see above) grants you access to your own account only, OAuth2 lets all WebMini users grant your application access to their account if they wish to do so.

All developers need to register their application before getting started. A registered OAuth2 application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

WebMini’s OAuth implementation supports the standard authorization code grant type. Developers should implement the web application flow described below to obtain an authorization code and then exchange it for a token. The implicit grant type is not supported.

Obtaining OAuth2 Client ID and Client Secret

  1. Go to the API OAuth Applications page in your user account.
  2. Click on Add Application.
  3. Enter the name and website of your application. Optionally, you can enter a description and a redirect URL.
  4. Once you added your application, you will see a page that tells you the Client ID and Client Secret of your application. Do not share your Client Secret with anyone as this would allow others to abuse your API access!

User Authentication with OAuth2

In order to gain API access to a user’s account, you have to let the user authenticate using OAuth2. The authenticating process is comprised of several steps:

1. Redirect users to request WebMini access

From your website, link to the following WebMini page:

https://my.webmini.com/en/user/oauth/?response_type=code&client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}

Important: If you are using OAuth with WebMini Itemplatform and want to authorize an Itemplatform user, we recommend using a different URL that makes the authorization process faster and easier for the user. Please read our Itemplatform API documentation for details.

Parameters:

Name Type Description
client_id String Required. The client ID you received from WebMini when you registered your application.
response_type String Required. Sets the authorization code grant type. In most cases you should set this parameter to the value "code".
scope String Required. A comma separated list of scopes.
redirect_uri String The URL in your application users will be sent to after authorization. 
state String An unguessable random string. It is used to protect against cross-site request forgery attacks.

2. WebMini redirects back to your website

If the user accepts your request, WebMini redirects back to your website with a code parameter as well as the state you provided in the previous step. If the states don’t match, the request has been created by a third party and the process should be aborted.

3. Exchange code for an access token

POST https://my.webmini.com/user/oauth_token/

Parameters:

Name Type Description
client_id String Required. The client ID you received from WebMini when you registered your application.
client_secret String Required. The client secret you received from WebMini when you registered your application.
grant_type String Required. Set this parameter to the value "authorization_code".
code String Required. The code parameter you received in Step 2.
redirect_uri String The URL in your application users will were sent to after authorization. Must match the value you provided in the first step.
state String The unguessable random string you provided in Step 1.

The response will be a JSON object like this:

{
	"access_token": "...",
	"expires_in": 3600,
	"token_type": "bearer",
	"scope": "scope1 scope2 ...",
	"refresh_token": "..."
}

Store the access_token at a safe place, e.g. encrypted in your database. You will use this token to gain access to the authenticated user’s account (based on the granted scopes). Please note that an acess token only grants short-term access and becomes invalid after the amount of seconds specified by expires_in. If you need long-term access to the granted resources, you also need to store the refresh_token and use it to retrieve a new access_token once the current one expired:

4. Use refresh_token to get new access_token (optional, only needed for long-term access)

POST https://my.webmini.com/user/oauth_token/

Parameters:

Name Type Description
client_id String Required. The client ID you received from WebMini when you registered your application.
client_secret String Required. The client secret you received from WebMini when you registered your application.
grant_type String Required. Set this parameter to the value "refresh_token".
refresh_token String Required. The refresh token you received in Step 3.

The response will be a JSON object like this:

{
	"access_token": "...",
	"expires_in": 3600,
	"token_type": "bearer",
	"scope": "scope1 scope2 ..."
}

Authenticating with an OAuth2 access_token

You can use the OAuth2 access_token to access the WebMini API on behalf of the authenticated user by providing it in the Authorization HTTP header of your API request:

Authorization: Bearer ACCESS-TOKEN

For example, in curl you can set the Authorization header like this:

curl -H "Authorization: Bearer ACCESS-TOKEN" https://my.webmini.com/api/v1/testservice/auth