Authentication

You'll need to authenticate your requests to access any of the endpoints in the VDH-Solar API. In this guide, we'll look at how authentication works. VDH-Solar uses a bearer token to authenticate your API requests.

Use API token

To use the VDH-Solar API you need to have an user account on the website. If you don't yet have an account, you can create one here. Once you have an account, you can generate an API key in the VDH-Solar dashboard under API tokens.

Use Oauth2

VDH-Solar also supports OAuth2. You can use the OAuth2 token to authenticate your requests. To use OAuth2 you need to have an user account on the website. If you don't yet have an account, you can create one here. Once you have an account, you can request an OAuth2 application in your VDH-Solar dashboard under OAuth2 Application.

Get auth code

To start the authentication process, you need to redirect the user to the authorization URL. The user will be asked to log in and approve the requested permissions. If the user approves the request, they will be redirected back to your application with an authorization code.

Name
client_id
Type
string
Description
The client id that you received when you created the OAuth2 application.
Name
redirect_uri
Type
string
Description
The redirect uri that you set when you created the OAuth2 application.
Name
response_type
Type
string
Description
The response type that you want to use. For the OAuth2 authorization code flow, you should use code.
Name
state
Type
string
Description
A random string that you can use to protect against CSRF attacks.
Name
scope
Type
string
Description
The scope of the access request. The possible values are email, name, add-to-cart, add-to-project, list-product, list-stock, create-order, list-order and delete-order. If you want to use multiple scopes, you can separate them with a space.
Name
prompt
Type
string
Description
The prompt parameter can be used to control the authentication flow of the authorization server. The possible values are "none", "consent", or "login".

Request

$query = http_build_query([
  'client_id' => '0Aa00a000-00aa-0a00-AAAA-000aaa0a000a',
  'redirect_uri' => 'https://your-application.com/auth/callback',
  'response_type' => 'code',
  'state' => 'KHDGJKKJDF',
  'scope' => 'email name add-to-cart',
  'prompt' => 'none',
]);

$authorize_path = 'https://vdh-solar.nl/oauth/authorize';
header("Location: {$authorize_path}?{$query}");
exit;

Get access token

Once you have the authorization code, you can exchange it for an access token. You can use the access token to authenticate your requests to the VDH-Solar API.

Name
grant_type
Type
string
Description
The grant type that you want to use. For the OAuth2 authorization code flow, you should use authorization_code.
Name
client_id
Type
string
Description
The client id that you received when you created the OAuth2 application.
Name
client_secret
Type
string
Description
The client secret that you received when you created the OAuth2 application.
Name
redirect_uri
Type
string
Description
The redirect uri that you set when you created the OAuth2 application.
Name
code
Type
string
Description
The authorization code that you received in the previous step.

Request

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://vdh-solar.nl/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type' => 'authorization_code',
        'client_id' => '0Aa00a000-00aa-0a00-AAAA-000aaa0a000a',
        'client_secret' => '0AAAAaaA0aaaAaaAAAaaaA0AOaA00AaaaaAaAa0a',
        'redirect_uri' => 'https://your-application.com/auth/callback',
        'code' => $request->code, // This should come from your request
    ]),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/x-www-form-urlencoded"
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    $responseArray = json_decode($response, true);
    $access_token = $responseArray['access_token'] ?? null;
    echo "Access Token: " . $access_token;
}

Response

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ...",
  "refresh_token": "def...",
}

Refreshing Tokens

If you have a refresh token, you can use it to get a new access token. Refresh tokens are long-lived and can be used to get a new access token when the current access token expires.

Name
grant_type
Type
string
Description
The grant type that you want to use. For the OAuth2 refresh token flow, you should use refresh_token.
Name
refresh_token
Type
string
Description
The refresh token that you received when you exchanged the authorization code for an access token.
Name
client_id
Type
string
Description
The client id that you received when you created the OAuth2 application.
Name
client_secret
Type
string
Description
The client secret that you received when you created the OAuth2 application.
Name
scope
Type
string
Description
The scope of the access request. Please check the options in the Get auth code section.

Request

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://vdh-solar.nl/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type' => 'refresh_token',
        'refresh_token' => 'def...', // Replace with actual refresh token
        'client_id' => '0Aa00a000-00aa-0a00-AAAA-000aaa0a000a',
        'client_secret' => '0AAAAaaA0aaaAaaAAAaaaA0AOaA00AaaaaAaAa0a',
        'scope' => 'email name add-to-cart'
    ]),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/x-www-form-urlencoded"
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

Response

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ...",
  "refresh_token": "def...",
}

Test your token

You can use this ping endpoint to test if your token is working correctly.

Always keep your token safe and reset it if you suspect it has been compromised.

Request

GET

/v1/ping

$client = new \VdhSolar\ApiClient('eyJ...');

$client->ping();

Successfull Response

{
  "result": "pong"
}

Error response

{
  "type": "api_unauthenticated",
  "message": "Unauthenticated",
  "documentation_url": "https://docs.vdh-solar.nl/authentication",
}