Concepts
| Concept | Description |
|---|---|
| File API | Public endpoint to upload/list/download the files. In the request to File API, client id, business type id and tenant id are being identified. Once the files are uploaded to File API by a publisher application, the authorized subscriber application can list, download and delete the files. |
| Business Type | The files which are related to the same “business” are functionally grouped in File types called “Business types”. File types are represented by an integer called “Business type id”. |
| Client Application | Client Applications are the users of the system. They are identified by a client Id. Client Applications are also authorized to tenantId(s). Client application needs to obtain a authentication token by using credentials (client id and client secret).The token includes client id, tenant id and the scopes of the application. Client Applications could be authorized either as publisher or subscriber of a business type. |
| Publisher | Publisher is a Client Application that can upload files of authorized business types and authorized tenants. The uploaded files can also be listed/downloaded. |
| Subscriber | Subscriber is a Client Application that can list/download/delete the files of authorized business types and authorized tenants. |
| Tenant | HR Core Client. Tenants are represented by tenant ids. |
Authentication
We follow current industry standards and best practices. Authentication/authorization is not an exception. As part of the Identity and Access Management Strategy for system-to-system integrations, the File API is based on OAuth 2.0 and the authorization grant Client Credentials. Every API consumer system will be provisioned in our API Gateway as a Client Application (App). Client ID and Client Secret will be provided to be used by Apps as credentials. Thus, Apps will be able then to authenticate and get an access token (JWT) within the response payload. Subsequent requests authorization will be based on that access token previously retrieved.
Tenant Authorization
Client Applications (apps) need to be authorized to the corresponding Tenant (HR Core Client) in order to consume the API. By default, the applications are authorized to TenantId: sandbox.
File Type Authorization
Client applications (apps) need to be authorized as publisher or subscriber of business types
By default,sandbox apps are authorized to the Sandbox File Types.
IP Whitelisting
The File API supports IP whitelisting that allows it to block the requests that are sent from non whitelisted IPs. In order to configure it, the below information needs to be provided via 4me request:
- Your Public IP(s) in CIDR format (for example:192.0.2.0/24) from where the request are sent to the File API
- Your ClientId used to send the request to File API
Supported File Types
The File API has been designed to support a specific set of use cases. This may be extended over time, based on customer feedback. See the Supported File Types clicking of the left menu.
Retention Period
The files will be physically deleted from Storage automatically after the retention period expires (1 month).
The metadata of the files (FileName, tenantId , BusinessTypeId, etc) is deleted after 6 months.
Curl Example
Here is an example of downloading a file using curl, available on most operating systems:
curl.exe https://fileapi.youforce.com/v1.0/files/%fileid%?role=subscriber ^
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ^
--header "Accept: application/octet-stream" ^
--output @C:/Youforce/somefile.xml
See also additional examples for powershell and .Net in Github.