device-authentication

Device authentication enhances security by requiring devices registering with or calling the Polycom
RealPresence DMA system to provide credentials that the system can authenticate.
In turn, the Polycom RealPresence DMA system may need to authenticate itself to an external SIP peer or
gatekeeper.
[tags: DMA]

Resource Root

https://localhost:8443/api/rest/device-authentication

Summary

Resources	Methods
https://localhost:8443/api/rest/device-authentication
https://localhost:8443/api/rest/device-authentication/token	GET Get the current (or a valid) device authentication token info used to generate trusted token device authentication values (provisioner or higher required). DELETE Delete/reset the current authentication token info, if any exists (administrator required).
https://localhost:8443/api/rest/device-authentication/token/generate	POST Using the provided values generate a device authentication token string valid for the current DMA instance.
https://localhost:8443/api/rest/device-authentication/token/decode	POST Using the provided value decode a device authentication token string.
https://localhost:8443/api/rest/device-authentication/inbound	GET Retrieves information list of device authentication for inbound. POST Creates a device authentication inbound object.
https://localhost:8443/api/rest/device-authentication/inbound/sip-device-authentication-inbound	GET Retrieves information of sip device authentication for inbound. PUT Updates information of sip device authentication for inbound.
https://localhost:8443/api/rest/device-authentication/inbound/{device-authentication-inbound-identifier}	GET Read a device authentication inbound. PUT Updates a device authentication inbound. DELETE Deletes a Device authentication inbound.
https://localhost:8443/api/rest/device-authentication/outbound	GET Retrieves information list of device authentication for outbound. POST Creates a device authentication outbound object.
https://localhost:8443/api/rest/device-authentication/outbound/{device-authentication-outbound-identifier}	GET Read a device authentication outbound. PUT Updates a device authentication outbound. DELETE Deletes a Device authentication outbound.

Resources

https://localhost:8443/api/rest/device-authentication

https://localhost:8443/api/rest/device-authentication/token

Methods

GET

Get the current (or a valid) device authentication token info
used to generate trusted token device authentication values (provisioner or higher required).
[tags: DMA]

Request

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-device-authentication-token-info+xml application/vnd.plcm.plcm-device-authentication-token-info+json	Retrieved token information successfully.
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: provisioner

DELETE

Delete/reset the current authentication token info, if any exists (administrator required).
[tags: DMA]

Request

Response

Status	Representation	Description
204		Current token deleted successfully.
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator

https://localhost:8443/api/rest/device-authentication/token/generate

Methods

POST

Using the provided values generate a device authentication token string valid for the current DMA instance.
Requires administrator rights.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-token-contents+xml

application/vnd.plcm.plcm-device-authentication-token-contents+json

Response

Status	Representation	Description
200	text/plain	Generated token
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator

https://localhost:8443/api/rest/device-authentication/token/decode

Methods

POST

Using the provided value decode a device authentication token string.
Requires administrator rights.
[tags: DMA]

Request

Representations

text/plain

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-device-authentication-token-contents+xml application/vnd.plcm.plcm-device-authentication-token-contents+json	Decoded token contents
400	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Token could not be decoded (invalid for this DMA, missing parts, etc.).
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator

https://localhost:8443/api/rest/device-authentication/inbound

Methods

GET

Retrieves information list of device authentication for
inbound.
[tags: DMA]

Request

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-device-authentication-inbound-list+xml application/vnd.plcm.plcm-device-authentication-inbound-list+json	Device authentication inbound information successfully retrieved
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Current user does not have permission to request information.
304		Device authentication inbound list records have not changed since the last GET. Note: The API client must provide the "plcm-device-authentication-inbound-list" representation's ETag value in the "If-None-Match" HTTP header to ensure conditional retrieval.This will improve network performance by reducing bandwidth consumption. If the API client chooses to exclude an ETag value from a previous, identical search in the "If-None-Match" header, then the HTTP response will contain the search results in the message body. The "plcm-device-authentication-inbound-list" ETag can be accessed from the initial search result's HTTP response header. Also, subsequent searches require the identical search filter to ensure an equivalent ETag value. This also assumes no other client made changes to the device authentication list for inbound on the server.

POST

Creates a device authentication inbound object. Any submitted ID is
ignored. The ID is assigned by the system.
Name and Password device authentication inbound are required and name
must be unique.
If a device authentication inbound pre-exists with the same name
the request fails.
DMA role required: administrator.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-inbound+xml

application/vnd.plcm.plcm-device-authentication-inbound+json

Response

Status	Representation	Description
201		Device authentication inbound created successfully. The ETag returned in the HTTP header represents the version of the device authentication for inbound.
400	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Bad request
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	External Device authentication for inbound with that name already exists.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Device authentication for inbound password is required and must be less than 128 characters.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Device authentication for inbound password must be less than 128 characters.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Device authentication for inbound name must be less than 128 characters.

https://localhost:8443/api/rest/device-authentication/inbound/sip-device-authentication-inbound

Methods

GET

Retrieves information of sip device authentication for inbound.
[tags: DMA]

Request

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-sip-device-authentication-settings+xml application/vnd.plcm.plcm-sip-device-authentication-settings+json	SIP device authentication setting information successfully retrieved
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Current user does not have permission to request information.
304		SIP device authentication inbound records have not changed since the last get. Note: The API client must provide the "plcm-sip-device-authentication" representation's ETag value in the "If-None-Match" HTTP header to ensure conditional retrieval. This will improve network performance by reducing bandwidth consumption. If the API client chooses to exclude an ETag value from a previous, identical search in the "If-None-Match" header, then the HTTP response will contain the search results in the message body. The "plcm-sip-device-authentication" ETag can be accessed from the initial search result's HTTP response header. Also, subsequent searches require the identical search filter to ensure an equivalent ETag value. This also assumes no other client made changes to the sip device authentication for inbound on the server.

PUT

Updates information of sip device authentication for inbound.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-sip-device-authentication-settings+xml

application/vnd.plcm.plcm-sip-device-authentication-settings+json

Response

Status	Representation	Description
204		SIP device authentication record successfully accepted.
428		SIP device authentication information has changed since the last retrieval. Note: The response will contain the ETag value and link that reflects the server's sip device authentication resource in the HTTP response header. The API client must supply the ETag in the message body that is bounded by the "entity-tag" XML tag. Refer to the "plcm-sip-device-authentication.xsd" for details.If the message body does not contain the ETag value, the server will look for the ETag in the "If-Match" header. The "plcm-sip-device-authentication" ETag can be accessed from the initial retrieval result's HTTP response header. Also, subsequent retrievals require the identical sip-device-authentication-identifier to ensure an equivalent ETag value. This also assumes no other client made changes to sip device authentication for inbound records on the server.
401	application/vnd.plcm.plcm-error+xml	User is not authorized to accept the sip device authentication
406	application/vnd.plcm.plcm-error+xml	Not Acceptable

https://localhost:8443/api/rest/device-authentication/inbound/{device-authentication-inbound-identifier}

Template Parameters

Name	Type	Description
device-authentication-inbound-identifier	xs:string	Device authentication identifier.

Methods

GET

Read a device authentication inbound.
[tags: DMA]

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-device-authentication-inbound+xml application/vnd.plcm.plcm-device-authentication-inbound+json	Device authentication for inbound information. Successfully retrieved.
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Current user does not have permission to request information.
304		Device authentication inbound record have not changed since the last get.Note: The API client must provide the "plcm-device-authentication-inbound" representation's ETag value in the "If-None-Match" HTTP header to ensure conditional retrieval. This will improve network performance by reducing bandwidth consumption. If the API client chooses to exclude an ETag value from a previous, identical search in the "If-None-Match" header, then the HTTP response will contain the search results in the message body. The "plcm-device-authentication-inbound" ETag can be accessed from the initial search result's HTTP response header. Also, subsequent searches require the identical search filter to ensure an equivalent ETag value. This also assumes no other client made changes to the device authentication for inbound on the server.

PUT

Updates a device authentication inbound.

DMA role required: administrator

[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-inbound+xml

application/vnd.plcm.plcm-device-authentication-inbound+json

Response

Status	Representation	Description
204		Device authentication inbound updated successfully. The ETag returned in the HTTP header represents the current version of the device authentication inbound.
400	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Bad request
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator
404	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	There is no template with the identifier supplied in the URL and/or the body of the request.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ID supplied in the URL and/or the body of the request cannot be parsed.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ID supplied in the URL does not match that supplied in the body of the request. Only one of these is required but if they are both supplied they must match.
412	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ETag supplied in the header and/or body does not match that on the server.This usually means that the template upon which the update is based has changed since the last time you accessed it.
428	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ETag is missing and required.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ETag in the header does not match that in the body Only one of these is required but if they are both supplied they must match.
428	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Device authentication inbound name already used.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The name of the device authentication inbound is required. The name must be between 1 and 128 characters.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The device authentication password is required and must be less than 128 characters.

DELETE

Deletes a Device authentication inbound. [tags: DMA]

Request

Response

Status	Representation	Description
204		Device authentication inbound deleted successfully.
400	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Bad request
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator
404	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	There is no device authentication inbound with the identifier supplied in the URL.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ID supplied in the URL cannot be parsed.

https://localhost:8443/api/rest/device-authentication/outbound

Methods

GET

Retrieves information list of device authentication for
outbound.
[tags: DMA]

Request

Query Parameters

Name	Type	Description
realm	xs:string	Return only outbound authentication devices that match the realm value.
username	xs:string	Return only outbound authentication devices that match the username value.

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-device-authentication-outbound-list+xml application/vnd.plcm.plcm-device-authentication-outbound-list+json	Device authentication outbound information successfully retrieved
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Current user does not have permission to request information.
304		Device authentication outbound list records have not changed since the last get. Note: The API client must provide the "plcm-device-authentication-outbound-list" representation's ETag value in the "If-None-Match" HTTP header to ensure conditional retrieval. This will improve network performance by reducing bandwidth consumption. If the API client chooses to exclude an ETag value from a previous, identical search in the "If-None-Match" header, then the HTTP response will contain the search results in the message body. The "plcm-device-authentication-outbound-list" ETag can be accessed from the initial search result's HTTP response header. Also, subsequent searches require the identical search filter to ensure an equivalent ETag value. This also assumes no other client made changes to the device authentication list for outbound on the server.

POST

Creates a device authentication outbound object. Any submitted ID is
ignored. The ID is assigned by the system.
Name and Password device authentication outbound are required and name
must be unique.
If a device authentication outbound pre-exists with the same name
the
request fails.
DMA role required: administrator.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-outbound+xml

application/vnd.plcm.plcm-device-authentication-outbound+json

Response

Status	Representation	Description
201		Device authentication outbound created successfully. The ETag returned in the HTTP header represents the version of the device authentication for outbound.
400	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Bad request
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	External Device authentication for outbound with that name already exists.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The name of the device authentication for outbound is required. The name must be between 1 and 128 characters.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Device authentication for outbound password is required and must be less than 128 characters.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Device authentication for outbound name must be less than 128 characters.

https://localhost:8443/api/rest/device-authentication/outbound/{device-authentication-outbound-identifier}

Template Parameters

Name	Type	Description
device-authentication-outbound-identifier	xs:string	Device authentication identifier.

Methods

GET

Read a device authentication outbound.
[tags: DMA]

Response

Status	Representation	Description
200	application/vnd.plcm.plcm-device-authentication-outbound+xml application/vnd.plcm.plcm-device-authentication-outbound+json	Device authentication for outbound information successfully retrieved.
403	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Current user does not have permission to request information.
304		Device authentication outbound record have not changed since the last get.Note: The API client must provide the "plcm-device-authentication-outbound" representation's ETag value in the "If-None-Match" HTTP header to ensure conditional retrieval. This will improve network performance by reducing bandwidth consumption. If the API client chooses to exclude an ETag value from a previous, identical search in the "If-None-Match" header, then the HTTP response will contain the search results in the message body. The "plcm-device-authentication-outbound" ETag can be accessed from the initial search result's HTTP response header. Also, subsequent searches require the identical search filter to ensure an equivalent ETag value. This also assumes no other client made changes to the device authentication for outbound on the server.
404	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	There is no device authentication outbound with the identifier supplied in the URL.

PUT

Updates a device authentication outbound.

DMA role required: administrator

[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-outbound+xml

application/vnd.plcm.plcm-device-authentication-outbound+json

Response

Status	Representation	Description
204		Device authentication outbound updated successfully. The ETag returned in the HTTP header represents the current version of the device authentication outbound.
400	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Bad request
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator
404	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	There is no template with the identifier supplied in the URL and/or the body of the request.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ID supplied in the URL and/or the body of the request cannot be parsed.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ID supplied in the URL does not match that supplied in the body of the request.Only one of these is required but if they are both supplied they must match.
412	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ETag supplied in the header and/or body does not match that on the server.This usually means that the template upon which the update is based has changed since the last time you accessed it.
428	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ETag is missing and required.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ETag in the header does not match that in the body Only one of these is required but if they are both supplied they must match.
428	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Device authentication outbound name already used.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The name of the device authentication outbound is required. The name must be between 1 and 128 characters.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The device authentication password is required and must be less than 128 characters.
404	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	There is no device authentication outbound with the identifier supplied in the URL.

DELETE

Deletes a Device authentication outbound. [tags: DMA]

Request

Response

Status	Representation	Description
204		Device authentication outbound deleted successfully.
400	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Bad request
401	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	Unauthorized. DMA role required: administrator
404	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	There is no device authentication outbound with the identifier supplied in the URL.
409	application/vnd.plcm.plcm-error+xml application/vnd.plcm.plcm-error+json	The ID supplied in the URL cannot be parsed.