Samsara Users API
The Users API from Samsara — 2 operation(s) for users.
OpenAPI Specification
openapi: 3.0.1
info:
description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
title: Samsara Users API
version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Users
paths:
/users:
get:
description: "Returns a list of all users in an organization. Users that have expired access will not be returned. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read Users** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: listUsers
parameters:
- description: The limit for how many objects will be in the response. Default and max for this value is 512 objects.
in: query
name: limit
schema:
format: int64
maximum: 512
minimum: 1
type: integer
- description: If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
in: query
name: after
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListUsersResponse'
description: List all users.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: List All Users
tags:
- Users
post:
description: "Add a user to the organization. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write Users** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: createUser
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
description: The user to create.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
description: Newly created user object with ID.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Create a User
tags:
- Users
x-codegen-request-body-name: user
/users/{id}:
delete:
description: "Delete the given user. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write Users** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: deleteUser
parameters:
- description: Unique identifier for the user.
in: path
name: id
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema:
$ref: '#/components/schemas/standardDeleteResponse'
description: A successful DELETE response is a 204 with no content.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Delete a User
tags:
- Users
get:
description: "Get a specific user's information. Users that have expired access will not be returned. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read Users** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: getUser
parameters:
- description: Unique identifier for the user.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
description: Returns the specified user.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Retrieve a User
tags:
- Users
patch:
description: "Update a specific user's information. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write Users** under the Setup & Administration category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: updateUser
parameters:
- description: Unique identifier for the user.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
description: Updates to the user.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
description: Updated user object with ID.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Update a User
tags:
- Users
x-codegen-request-body-name: user
components:
schemas:
UserRoleAssignment:
description: A role that applies to a user. If the role has a `tag`, then the role applies for that tag. If there is no `tag`, then the role applies at the organizational level. A user may have many tag-specific roles, but may only have one organizational level role. If the organizational level role has higher privileges than a tag-specific role, then the organizational role privileges will take precedence.
properties:
expireAt:
$ref: '#/components/schemas/UserExpireAt'
role:
$ref: '#/components/schemas/UserRole'
tag:
$ref: '#/components/schemas/tagTinyResponse'
type: object
UserExpireAt:
description: For user account expiration, the access expiration datetime in RFC3339 format
example: '2025-08-13T19:08:25Z'
type: string
UserRole:
description: A user role object.
properties:
id:
description: The unique ID for the role.
example: 8a9371af-82d1-4158-bf91-4ecc8d3a114c
type: string
name:
description: The name of the role.
example: Full Admin
type: string
type: object
tagTinyResponse:
description: A minified tag object
properties:
id:
description: ID of the tag.
example: '3914'
type: string
name:
description: Name of the tag.
example: East Coast
type: string
parentTagId:
description: If this tag is part a hierarchical tag tree, this is the ID of the parent tag, otherwise this will be omitted.
example: '4815'
type: string
type: object
UserAuthType:
description: 'The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration. Valid values: `default`, `saml`.'
enum:
- default
- saml
type: string
paginationResponse:
description: Pagination parameters.
properties:
endCursor:
description: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view.
example: MjkY
format: string
type: string
hasNextPage:
description: True if there are more pages of results immediately available after this endCursor.
example: true
type: boolean
required:
- endCursor
- hasNextPage
type: object
UserName:
description: The first and last name of the user.
example: Bob Smith
type: string
UserId:
description: ID of the user.
example: '123'
type: string
UserResponse:
description: A single user.
properties:
data:
$ref: '#/components/schemas/User'
type: object
UpdateUserRequest:
description: The user update arguments
properties:
authType:
description: 'The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration. Valid values: `default`, `saml`.'
enum:
- default
- saml
type: string
expireAt:
description: For users with temporary access, this is the expiration datetime in RFC3339 format
example: '2025-08-13T19:08:25Z'
type: string
name:
description: The first and last name of the user.
example: Bob Smith
type: string
roles:
description: The list of roles that applies to this user. A user may have "organizational" roles, which apply to the user at the organizational level, and "tag-specific" roles, which apply to the user for a given tag.
items:
$ref: '#/components/schemas/CreateUserRequest_roles'
type: array
type: object
User:
description: A user object.
properties:
authType:
$ref: '#/components/schemas/UserAuthType'
email:
$ref: '#/components/schemas/UserEmail'
id:
$ref: '#/components/schemas/UserId'
name:
$ref: '#/components/schemas/UserName'
roles:
$ref: '#/components/schemas/UserRoles'
required:
- authType
- email
- id
- name
- roles
type: object
ListUsersResponse:
description: A list of users.
properties:
data:
description: A list of users.
items:
$ref: '#/components/schemas/User'
type: array
pagination:
$ref: '#/components/schemas/paginationResponse'
type: object
UserRoles:
description: The list of roles that applies to this user. A user may have "organizational" roles, which apply to the user at the organizational level, and "tag-specific" roles, which apply to the user for a given tag.
items:
$ref: '#/components/schemas/UserRoleAssignment'
type: array
CreateUserRequest:
description: The user creation arguments
properties:
authType:
description: 'The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration. Valid values: `default`, `saml`.'
enum:
- default
- saml
type: string
email:
description: The email address of this user.
example: user@company.com
type: string
expireAt:
description: For users with temporary access, this is the expiration datetime in RFC3339 format
example: '2025-08-13T19:08:25Z'
type: string
name:
description: The first and last name of the user.
example: Bob Smith
type: string
roles:
description: The list of roles that applies to this user. A user may have "organizational" roles, which apply to the user at the organizational level, and "tag-specific" roles, which apply to the user for a given tag.
items:
$ref: '#/components/schemas/CreateUserRequest_roles'
type: array
required:
- authType
- email
- name
- roles
type: object
UserEmail:
description: The email address of this user.
example: user@company.com
type: string
standardDeleteResponse:
description: A successful DELETE response is a 204 with no content.
example: <empty content>
type: string
standardErrorResponse:
description: Error response
properties:
message:
description: The message of the error.
example: An error has occurred.
type: string
requestId:
description: The ID of the request.
example: 8916e1c1
type: string
type: object
CreateUserRequest_roles:
description: A role that applies to a user. If the role has a `tagId`, then the role applies for that tag. If there is no `tagId`, then the role applies at the organizational level. A user may have many tag-specific roles, but may only have one organizational role. If the organizational level role has higher privileges than a tag-specific role, then the organizational role privileges will take precedence.
properties:
roleId:
description: The unique ID for the role.
example: 8a9371af-82d1-4158-bf91-4ecc8d3a114c
type: string
tagId:
description: ID of the tag this role applies to.
example: '3914'
type: string
required:
- roleId
type: object
securitySchemes:
AccessTokenHeader:
type: http
scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
explorer-enabled: true
proxy-enabled: true