Remote Identity API
The Identity API from Remote — 2 operation(s) for identity.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Identity API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Identity
paths:
/v1/employee/current:
get:
callbacks: {}
deprecated: false
description: Returns user and company information for the authenticated employee.
operationId: get_v1_employee_current
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
security:
- OAuth2Assertion: []
summary: Get employee token identity
tags:
- Identity
/v1/identity/current:
get:
callbacks: {}
description: 'Shows information about the entities that can be controlled by the current auth token.
'
operationId: get_v1_identity_current
parameters:
- description: 'This endpoint works with any of the access tokens provided. You can use an access
token obtained through the Client Credentials flow, the Authorization Code flow, or the Refresh Token flow.
'
example: Bearer <ANY ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityCurrentResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken: []
OAuth2AuthorizationCode: []
OAuth2ClientCredentials: []
summary: Get token identity
tags:
- Identity
components:
schemas:
IdentityUser:
description: The user (company manager) associated with the current authentication token. Represents the person who authorized access to the company's data.
example:
email: email@example.com
id: 4117f18a-5ccf-473a-b970-608b75f5fafb
name: Jane Smith
status: created
properties:
email:
description: The email address of the user who authorized the token.
type: string
id:
description: The unique identifier (UUID) of the user.
type: string
name:
description: The full name of the user who authorized the token.
type: string
status:
description: The current account status of the user on the Remote platform.
type: string
required:
- email
- name
- id
- status
title: IdentityUser
type: object
ParameterError:
example:
code: invalid_param
message: Invalid parameter
param: employment_id
properties:
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
param:
description: The parameter that lead to the error message.
type: string
required:
- code
- message
- param
title: ParameterError
type: object
UnauthorizedResponse:
description: Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.
example:
message: Unauthorized
properties:
message:
pattern: Unauthorized
type: string
required:
- message
title: UnauthorizedResponse
type: object
IdentityClientCredentialsResponse:
description: Returned when the current token was obtained via the OAuth2 Client Credentials flow. Contains the integration's client ID and details, but no company or user information since client credentials tokens are not scoped to a specific company.
example:
data:
client_id: 1pws9iw986yq1ec57h159q29l
integration:
contact_email: partner_admin@example.com
display_name: Integration Display Name
name: integration_partner
properties:
data:
properties:
client_id:
description: The OAuth2 client ID used to obtain this token.
type: string
integration:
$ref: '#/components/schemas/IdentityIntegration'
required:
- client_id
- integration
type: object
required:
- data
title: IdentityClientCredentialsResponse
type: object
UnprocessableEntityResponse:
anyOf:
- properties:
errors:
type: object
required:
- errors
type: object
- properties:
message:
oneOf:
- type: string
- $ref: '#/components/schemas/ParameterError'
- items:
$ref: '#/components/schemas/ParameterError'
title: ParameterErrors
type: array
- $ref: '#/components/schemas/ActionError'
- items:
$ref: '#/components/schemas/ActionError'
title: ActionErrors
type: array
required:
- message
type: object
example:
errors:
some_field:
- is invalid
title: UnprocessableEntityResponse
type: object
NotFoundResponse:
description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
example:
message: '{resource} not found'
properties:
message:
description: A message indicating which resource was not found.
pattern: Not Found
type: string
title: NotFoundResponse
type: object
IdentityCustomerAccessTokenResponse:
description: Returned when the current token is a Customer API Token. These tokens are used by companies accessing their own data directly (not through an integration partner), so only company and user information is included — there are no integration credentials.
example:
data:
company:
id: afe4dc8d-0c4a-41fe-9fbf-62b752524bde
name: Company
user:
email: email@example.com
id: 4117f18a-5ccf-473a-b970-608b75f5fafb
name: Jane Smith
status: created
properties:
data:
properties:
company:
$ref: '#/components/schemas/IdentityCompany'
user:
$ref: '#/components/schemas/IdentityUser'
required:
- company
- user
type: object
required:
- data
title: IdentityCustomerAccessTokenResponse
type: object
IdentityCompany:
description: The company that the current authentication token is scoped to. Only present when using a company-scoped access token or customer API token.
example:
id: afe4dc8d-0c4a-41fe-9fbf-62b752524bde
name: Company
properties:
id:
description: The unique identifier (UUID) of the company. Use this ID when making subsequent API calls that require a company reference.
type: string
name:
description: The registered name of the company on the Remote platform.
type: string
required:
- name
- id
title: IdentityCompany
type: object
BadRequestResponse:
description: Returned when the request is malformed or contains invalid parameters. The message may be a simple string or a structured object with a code and detailed message.
example:
message: invalid {resource}
oneOf:
- properties:
message:
description: A human-readable error message describing what was wrong with the request.
type: string
required:
- message
type: object
- properties:
message:
properties:
code:
type: string
message:
type: string
required:
- code
- message
type: object
type: object
title: BadRequestResponse
type: object
IdentityCompanyAccessTokenResponse:
description: 'Returned when the current token was obtained via the OAuth2 Authorization Code flow and is scoped to a specific company managed by an integration partner. Contains the full context: the integration''s credentials, the company being accessed, and the user who authorized access.'
example:
data:
client_id: 1pws9iw986yq1ec57h159q29l
company:
id: afe4dc8d-0c4a-41fe-9fbf-62b752524bde
name: Company
integration:
contact_email: partner_admin@example.com
display_name: Integration Display Name
name: integration_partner
user:
email: email@example.com
id: 4117f18a-5ccf-473a-b970-608b75f5fafb
name: Jane Smith
status: created
properties:
data:
properties:
client_id:
description: The OAuth2 client ID of the integration partner that obtained this token.
type: string
company:
$ref: '#/components/schemas/IdentityCompany'
integration:
$ref: '#/components/schemas/IdentityIntegration'
user:
$ref: '#/components/schemas/IdentityUser'
required:
- client_id
- company
- integration
- user
type: object
required:
- data
title: IdentityCompanyAccessTokenResponse
type: object
ForbiddenResponse:
description: Returned when the authenticated user or token does not have permission to perform the requested action. Check that the token has the required OAuth2 scopes and that the user has the necessary role.
example:
message: Forbidden
properties:
message:
pattern: Forbidden
type: string
required:
- message
title: ForbiddenResponse
type: object
TooManyRequestsResponse:
description: Returned when the API rate limit has been exceeded (HTTP 429). Wait before retrying. Check the `Retry-After` response header for the recommended wait time.
example:
message: Too many requests
properties:
message:
pattern: Too many requests
type: string
title: TooManyRequestsResponse
type: object
IdentityIntegration:
description: Details about the integration partner associated with the current authentication token.
example:
contact_email: partner_admin@example.com
display_name: Integration Display Name
name: integration_partner
properties:
contact_email:
description: The primary contact email address registered for this integration partner.
type: string
display_name:
description: The human-readable display name of the integration partner, as shown to users.
type: string
name:
description: The unique machine-readable identifier for the integration partner. Used internally to reference this integration.
type: string
required:
- contact_email
- display_name
- name
title: IdentityIntegration
type: object
SuccessResponse:
description: A generic success response returned by operations that don't produce a specific resource (e.g., updates, deletes).
example:
data:
status: ok
properties:
data:
properties:
status:
description: The result status. Always `"ok"` for successful operations.
type: string
type: object
required:
- data
title: SuccessResponse
type: object
ActionError:
properties:
action:
description: The action that lead to the error message.
type: string
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
required:
- code
- message
- action
title: ActionError
type: object
IdentityCurrentResponse:
description: 'The response from `GET /v1/identity/current`. Returns information about the entities associated with the current authentication token. The shape of the response depends on the type of token used:
- **Client Credentials Token**: Returns the integration''s `client_id` and details. No company or user context.
- **Company Access Token** (Authorization Code flow): Returns full context — integration credentials, the company being accessed, and the authorizing user.
- **Customer API Token**: Returns only the company and user. No integration credentials since the company is accessing its own data directly.'
example:
data:
client_id: 1pws9iw986yq1ec57h159q29l
integration:
contact_email: partner_admin@example.com
display_name: Integration Display Name
name: integration_partner
oneOf:
- $ref: '#/components/schemas/IdentityClientCredentialsResponse'
- $ref: '#/components/schemas/IdentityCompanyAccessTokenResponse'
- $ref: '#/components/schemas/IdentityCustomerAccessTokenResponse'
title: IdentityCurrentResponse
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2Assertion:
description: 'Authenticate as the employee using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol.
'
flows:
clientCredentials:
scopes:
address:read: address:read
address:write: address:write
bank_account:read: bank_account:read
bank_account:write: bank_account:write
document:read: document:read
document:write: document:write
emergency_contact:read: emergency_contact:read
emergency_contact:write: emergency_contact:write
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
expense:read: expense:read
incentive:read: incentive:read
payroll: payroll
payslip:read: payslip:read
personal_detail:read: personal_detail:read
personal_detail:write: personal_detail:write
time_and_attendance: time_and_attendance
timeoff:read: timeoff:read
timeoff:write: timeoff:write
timesheet:read: timesheet:read
tokenUrl: /auth/oauth2/token
x-assertionType: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
type: oauth2
OAuth2AuthorizationCode:
description: 'Authenticate as the token authorizer using `authorization_code` / `refresh_token` grants in the OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
refreshUrl: /auth/oauth2/token
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2ClientCredentials:
description: 'Authenticate using `client_credentials` grant in the OAuth 2.0 protocol.
'
flows:
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2