Tämän osion artikkelit

Tehden API (for developers)

Avatar
Laura Vesanto
  • Päivitetty
Seuraa

Here's a short introduction to the Tehden API. The API follows the OAuth 2.0 specification. Text encoding is always UTF-8. Keep in mind that at the moment the API can change without notice. Remember to always use API version 1. You can access Tehden API documentation here: apidoc.tehden.com

Adding a new client

If you need a new client you can request it from api.support@tehden.com

Getting an access token

Tehden supports two different grant types for getting an access token: authorization code and password.
  • The "password" method uses API client specific user credentials. This is the recommended method.
  • The "authorization code" method has two steps and requires that an end-user approves the request.

Authorization code: Asking for authorization

The client redirects the user to 

GET https://somecompany.tehden.com/oauth/oauser/authorize

Parameters in URL (because it's a redirect).

Parameters

  • client_id: client to be authorized
  • response_type: defines authorization type, currently Tehden only supports "code" (Authorization code).
  • (optional) redirect_uri: must be in the same domain as what is stored in the database during registering
  • (optional) scope: space delimited list of requested scopes
  • (optional) state: a string that is always returned the same to the client, for state handling on client side

Result

  • If allowed, the user is redirected to the URL in the database (or parameters) with response parameters
  • redirect_uri?state=WHAT_WAS_GIVEN&code=AUTHORIZATION_CODE

Authorization code: Getting access token with authorization code

Client must authenticate either by

  • Authorization header "Authorization: Basic HASH_DIGEST" where HASH_DIGEST is base64 encoded string of "client_id:client_secret"
  • Adding client_id and client_secret as GET/POST parameters

GET/POST https://somecompany.tehden.com/oauth/oaclient/token

Parameters

  • grant_type: Tehden supports "authorization_code" which is used to verify user's approval
  • code: the authorization code
  • redirect_uri: must be identical with the redirect_uri given in the "Authorization code: Asking for authorization" part
  • + client credentials (client_id and client_secret) if authenticating using GET/POST parameters

Result

JSON object with the following fields:

  • access_token: access token used to access the API
  • expires_in: time in seconds after which the access token expires
  • token_type: "Bearer" supported by Tehden
  • scope: list of scopes allowed, string delimited by spaces
  • refresh_token: a token that can be used to get a new access token after it expires

After the response the authorization code is unusable.

Password: Requesting an access token

Client must authenticate either by

  • Authorization header "Authorization: Basic HASH_DIGEST" where HASH_DIGEST is base64 encoded string of "client_id:client_secret"
  • Adding client_id and client_secret as GET/POST parameters

GET/POST https://somecompany.tehden.com/oauth/oaclient/token

Parameters

  • grant_type: Tehden supports "password" which is used for API client specific users
  • username: the username of the API client user
  • password: the password of the API client user
  • redirect_uri: must be identical with the redirect_uri given in the "Authorization code: Asking for authorization" part
  • + client credentials (client_id and client_secret) if authenticating using GET/POST parameters

Result

  • JSON object with the following fields
  • access_token: access token used to access the API
  • expires_in: time in seconds after which the access token expires
  • token_type: "Bearer" supported by Tehden
  • scope: list of scopes allowed, string delimited by spaces
  • refresh_token: a token that can be used to get a new access token after it expires

Refreshing access token

Client must authenticate the same way as is described in "Getting access token with authorization code".

GET https://somecompany.tehden.com/oauth/oaclient/token

Parameters in URL

Parameters

  • grant_type: string "refresh_token"
  • refresh_token: the refresh token aquired earlier
  • (optional) scope: if asking for an additional scope
  • + client credentials (client_id and client_secret) if authenticating using GET/POST parameters

Result

  • The same JSON as in the previous "Getting access token with authorization code" section

Making API calls

GET/POST ;https://somecompany.tehden.com/api/module/method

where "module" can be e.g. company, customer, general and "method" is the function name.

Authorization header "Authorization: Bearer HASH_DIGEST" where HASH_DIGEST is base64 encoded string of the access token.

API version must be defined either as a GET parameter (e.g. "version=1") or as an Accept header (e.g. "Accept: application/vnd.tehden.api-v1+json").

Language code must be set either as a GET parameter (e.g. "language=fi") or as an Accept-Language header (e.g. "Accept-Language: fi"). Valid values at the moment are "fi" and "en".

The response is in JSON.

Errors

Possible error codes

  • Bad request 400 = bad syntax or something missing
  • Unauthorized 401 = problem with authorization
  • Forbidden 403 = token does not have required scope
  • Not found 404 = valid syntax, but does not exist
  • Internal error 500 = server side problems
  • Not implemented 501 = resource not implemented

Testing

It is possible to test the API using the following settings on a test server. Replace "somecompany" with the subdomain of your company.

Example

The following example tries to do everything the easiest way possible. We will only use the GET method here to keep things simple. Normally you should always use the POST method.

After the application has been registered to Tehden, you will have a client id (e.g. "MyApiClient") and a client secret (e.g. "MySecret"). The application also has to have a redirect URI (e.g. "https://www.example.com/apicallback") where the client browser will be redirected after the user allows the application to access Tehden.

Let's start by authorizing the application "MyApiClient" to use Tehden as the current user in company "Some Company". You need to be logged in as a Tehden user in order for this to work.

GET https://somecompany.tehden.com/oauth/oauser/authorize?client_id=MyApiClient&response_type=code

Once you allow access you are redirected to the redirect uri which was defined during the client application registration. In this example the redirect looks like this

GET https://www.example.com/apicallback?code=1v3ba0f2797fcfebdefc9ac5ba8dd839fbab579110cc14abf0eaabe0bc7d

The code is the authorization code which will be used to get the access token.

GET https://somecompany.tehden.com/oauth/oaclient/token?grant_type=authorization_code&code=1v3ba0f2797fcfebdefc9ac5ba8dd839fbab579110cc14abf0eaabe0bc7d&client_id=MyApiClient&client_secret=MySecret

We get the following response in JSON.
{"access_token":"1v3da014885cad15ca57b506112a51771b1ac870b9dbc85947a02e483966",
"expires_in":3600,
"token_type":"bearer",
"scope":"",
"refresh_token":"1vb3c273bad35e9cfc6dcc97f02631cca7bbcd2f25fcb19b321a2c855d84"}

From now on we can make API calls using the access_token. In this example it will expire after an hour. The API will also respond by giving an "invalid_grant" error if you try to use an expired access token. You can get a new access token using the refresh_token.

GET https://somecompany.tehden.com/oauth/oaclient/token?grant_type=refresh_token&refresh_token=1vb3c273bad35e9cfc6dcc97f02631cca7bbcd2f25fcb19b321a2c855d84&client_id=MyApiClient&client_secret=MySecret

{"access_token":"1v98951702e28f9e4795c31c949131da627049221000315df8079ecefecc",
"expires_in":3600,
"token_type":"bearer",
"scope":"",
"refresh_token":"1vf41d4aaf2dddf85c5fe5fdc27f599da48374fa96b5d9eb729ca2183e11"}

An example API call to get all product groups:

GET https://somecompany.tehden.com/api/product/getProductGroups?version=1

Remember to add the Authorization header. In this case it will be (using the latest access token encoded in base64, everything written on one line):

Authorization: Bearer MXY5ODk1MTcwMmUyOGY5ZTQ3OTVjMzFjOTQ5MTMxZGE2MjcwNDkyMjEwMDAzMTVkZjgwNzllY2VmZWNj

Same request in curl

curl \
-H "Accept: application/vnd.tehden.api-v1+json" \
-H "Accept-Language: fi" \
-H "Authorization: Bearer MXY5ODk1MTcwMmUyOGY5ZTQ3OTVjMzFjOTQ5MTMxZGE2MjcwNDkyMjEwMDAzMTVkZjgwNzllY2VmZWNj" \
https://somecompany.tehden.com/api/product/getProductGroups
 
Minimal PHP example
 
<?php

    header('Content-Type: text/plain');

    // Fill in the access token
    $accessToken = '<valid_access_token_here>';

    // Change the product_ids
    $post = array(
        'product_ids' => array(
            '8319e522-8a6e-4cdf-a605-075e0c4a8d18',
            'db86f94b-de3b-49ab-8bf3-8e3b14bc6b67'
        )
    );
   
    $headers = array(
        'Accept: application/vnd.tehden.api-v1+json',
        'Accept-Language: fi',
        'Authorization: Bearer ' . base64_encode($accessToken)
    );

    $ch = curl_init('https://somecompany.tehden.com/api/product/getProducts');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);   
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post));

    $response = curl_exec($ch);
    curl_close($ch);

    $response = json_decode($response);
   
    var_dump($response);

Aiheeseen liittyvät artikkelit

Kommentit

0 kommenttia

Kirjaudu sisään jättääksesi kommentin.