Smag Link was designed for agricultural organizations and partners who want to connect their digital solutions with the SMAG ecosystem.
Smag Link offers a set of business reference data and an API platform based on AgGateway ADAPT, making it easy to interoperate with major players in the agricultural world : publishers, machinery manufacturers, technical institutes, startups, etc.
The Smag Link APIs are privately accessible :
To access the APIs, the first step is to create a developer account on the API portal. The portal will present documentation for all APIs subscribed to by your organization. See : How to create my developer account ?
To access data belonging to a specific user, a token is required to formalize their consent. See : How to obtain a token ?
To access data belonging exclusively to SMAG, an APIKEY is required to formalize the acquisition of this data. See : How to obtain an APIKEY ?
Once this access is obtained, to effectively leverage the Smag Link APIs, feel free to consult the sections "How are the endpoints organized ?", "How is Smag Link data structured ?" as well as our Use cases.
Sign up" option in the menu. Fill in your e-mail address, your name and a password.
Mandatory step : afterwards, please contact us at developers@smag.tech so that we can assign the necessary access rights to the APIs subscribed by your organization to your account.
Once completed, you can log in to the API portal using the "Sign in" option in the menu and explore the documentation for all APIs.
Once your developer account has been associated with the necessary rights by Smag, it will be linked to a subscription key that needs to be provided with each API call. You can retrieve this key from your API portal Profile by clicking on "Show" :
Note: It's recommended to use the primary key, but the secondary key works equally well and allows key rotation if necessary.
Moreover, in case of theft or suspected compromise, you can independently regenerate your key by clicking on "regenerate".
To access a specific user's data via API, any third-party software must first request their explicit consent. SMAG, as the holder of user data, will not provide any data without this consent.
This agreement is formalized in the form of a JWT (JSON Web Token), to be transmitted to the SMAG API with each call using the SmagAuthorization header parameter.
This token includes :
The application ID identifying the third-party software
The user's Smag account involved
A token remains valid for 12 hours. Once expired, it can be refreshed. See : How to refresh a token ?
You need to register your application with our team via email at developers@smag.tech. An application ID will be assigned to you.
If your application operates in multiple environments (e.g., development, testing, production, etc.), a separate application ID should be requested for each environment your application is deployed in.
The token generation tool allows for manual token retrieval for a given application ID and compte Smag. This tool is particularly useful during the development phase.
Firstly, the owner of the Smag account must sign in :
Upon signing in to the Smag account, a token without an application ID is automatically generated (which can be copied to the clipboard by clicking Copy) :
However, this token was generated without an application ID. Therefore, it's necessary to specify the application and click Refresh to generate a complete and usable token for API calls :
If you're developing a client application that allows user interaction, follow these steps :
The application requests from the Smag Link Authentication API a URL for the Smag account login screen (login URL) using the build_url endpoint
The API returns this login URL (specific to the application)
The application redirects the user to this URL, presenting them with the Smag account login screen
The user enters his credentials
After authentication, the user is redirected to your application's callback URL (which you should have previously communicated to our team : developers@smag.tech), with the transmission of the token. Your application can use this token for various Smag Link API calls.
flowchart TD; App([Application]) Auth[[Authentication API]] Login([Smag account login screen]) User((User)) App -- 1. asks for a login URL --> Auth Auth -- 2. returns the login URL --> App App -- 3. redirects to the login URL --> Login Login o-- 4. enters his credentials --o User Login -- "5. redirects to the callback URL + token" --> App
To request a login URL, you need to call the POST Request a redirection URI for the Smag account Login page endpoint from the Authentication API, documented on the API portal as shown below :
This endpoint is of type POST because a JSON object needs to be sent in the body :
{
"AdditionalValues":
{
"application_id" : "******************", // Your application ID provided by Smag
"displayLogin" : 1 // To force the screen to start with the "login" tab
// (Or 0 to start with the "create account" tab)
}
}
Example of calling the endpoint using curl :
curl -v
-X POST "https://api.smag.tech/authentication-operational/v1/api/authentication/build_url"
-H "Content-Type: application/json-patch+json"
-H "Cache-Control: no-cache"
-H "Ocp-Apim-Subscription-Key: ***********************"
--data-raw "{
\"AdditionalValues\": {
\"application_id\": \"********************\",
\"displayLogin\": 1
}
}"
Note : In this call, as with all Smag Link API calls, you must obligatoirement add the
header"Ocp-Apim-Subscription-Key" with your subscription key provided by the portal in the Profile tab.
If you're developing a scheduled/background task application where users can't interact, you should use this mode.
The process follows these steps :
The application requests a token from the Smag Link Authentication API using login/password credentials
These credentials have been coordinated with the Smag teams to perform expected operations while adhering to various performance, security, etc., constraints
The application process finally uses this token to make its SmagLink calls.
A token remains valid for 12 hours. After this period, it's possible to automatically refresh it.
To do so, you'll need to retrieve the refresh token contained within the JWT token and use the POST Renew a token after its expiration endpoint from the Authentication API :
This endpoint is of type POST because it requires sending the following JSON in the body of the call :
{
"applicationId" : "******************", // Your application ID provided by Smag
"refreshToken" : "****************" // The "refresh token" that was included with the token
}
Exeample of calling the endpoint using curl :
curl -v -X POST "https://api.smag.tech/authentication-operational/v1/api/oauth2/refresh_token"
-H "Content-Type: application/json-patch+json"
-H "Cache-Control: no-cache"
-H "Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••"
--data-raw "{
\"applicationId\": \"**************************\",
\"refreshToken\": \"**********************\"
}"
A new token, valid for 12 hours, will be returned in response by the endpoint.
Don't forget to provide the Ocp-Apim-Subscription-Key header as previously mentionned.
Note : The refresh token has a maximum validity of 30 days since its last usage.
Tokens are generated using an RS256 (RSA signature with SHA-256) encoding algorithm, asymmetric (utilizing a public key / private key pair).
In this system, the identity provider generates an unalterable signature using its private key. This signature can be validated by the recipient using a public key. Consequently, the token can be decoded using the tool https://jwt.io.
SMAG relies on a trusted third party for identity provisioning, ensuring security against attacks, particularly brute force attacks. Consequently, SMAG never has access to its users' login credentials.
An APIKEY is issued upon subscription by your organization to a data usage agreement belonging to SMAG, for a defined use case (especially: reference data).
This APIKEY needs to be communicated in calls to endpoints related to SMAG data covered by the contract, using the X-API-KEY header parameter.
A second parameter, the application ID, needs to be provided through the X-APP-ID header parameter. See How to obtain my application ID ?
Example on the CropProtectionProducts API :
Smag Link is organized into functional domains, with each domain corresponding to an API.
Each API is divided into different groups of endpoints called tags, these groups mainly corresponding to business entities.
Within a tag, you'll typically find :
an endpoint "Get all ...", allowing retrieval of a list of identifiers and names for all records corresponding to the requested business entity
an endpoint "Get a .../{uid}", enabling retrieval of detailed information for a specific record (identified by its UUID)
Smag Link data is structured following a data model heavily inspired by the AgGateway ADAPT standard, where we describe some fundamental concepts.
A compound identifier is a collection of identifiers for the same record in different computer systems (referred to as sources) that have exchanged data for this record.
Each system that receives a record with a compound identifier can subsequently transmit it to another system after adding its own identifier to the collection. Through this principle, any receiving system will be able to interoperate with all previous contributors to this record.
The structure of an entity with a compound identifier is as follows :
{
"uid" : "596cb84c-43a5...", // SMAG's UUID for the entity
"id" : // The compound identifier
{
"referenceId" : <integer>, // The reference number within the response dataset
// Caution: this number is regenerated with each call
"uniqueId" : // Collection of identifiers in other sources
[
{ // Identifier for a "XYZ" source
"id" : "***********", // The actual identifier
"idType" : "*****", // Identifier type: "LongInt", "String", "UUID", "URI"
"source" : "XYZ", // Source name
"sourceType" : "URI" // Source type. Can also be "GLN" (Global Location Number)
},
..., // Other identifiers for other sources
{ // Identifier for "Smag Link" source
"id" : "596cb84c-43a5...", // Reminder of the "uid" attribute
"idType" : "UUID",
"source" : "SmagLink",
"sourceType" : "URI"
}
]
}
}
Units of measure pose a challenge when transferring numerical values between systems. This implies that these systems have previously matched their unit references (to perform conversions).
To alleviate this complexity, ADAPT accompanies each unit with necessary information to facilitate its conversion into all units of the same dimension (for example: weight, volume, distance...), through a structure called unit of measure :
{
"id" : ..., // Unit's compound identifier
"code" : "****", // Unit code
"dimension" : "*****" // The base dimension of the unit (weight, volume, distance, ...)
"isReferenceForDimension" : <boolean>, // True if the unit is the "base unit" for its dimension
// (in this case, conversion calculations are unnecessary)
"scale" : <double>, // Multiplicative conversion factor
"offset" : <double> // Additive conversion factor
}
A numeric value is always accompanied by its unit of measure, structured as a numeric value :
{
"value" : <double>, // Numeric value
"unitOfMeasure" : <UnitOfMeasure> // Information about the unit of measure
}
Information regarding how to display a numeric value is described within a numeric representation structure (many attributes are often left unpopulated as they are optional) :
{
"decimalDigits" : <integer>, // Number of displayed decimal places
"minValue" : <NumericValue>, // Minimum value (for slider-like presentations)
"maxValue" : <NumericValue>, // Maximum value (for slider-like presentations)
"description" : "*****", // Explanatory text accompanying the numeric value
...
}
Lastly, a numeric representation value aggregates numeric value and numeric representation, adding presentation-related information about the value, such as color (for instance : red for negative values, green for positives...)
For any technical inquiries related to Smag Link, you can contact us at developers@smag.tech.