ExTwilio.Capability (ExTwilio v0.8.2) View Source

Capability tokens are used to sign communications from devices to Twilio. You create a token on your server, specify what capabilities you would like your device to have, then pass the token to your client to use. The tokens generated are JSON Web Tokens (JWT).

Example

ExTwilio.Capability.new
|> ExTwilio.Capability.allow_client_incoming("tommy")
|> ExTwilio.Capability.allow_client_outgoing("APabe7650f654fc34655fc81ae71caa3ff")
|> ExTwilio.Capability.token
"xxxxx.yyyyy.zzzzz"

Link to this section Summary

Types

outgoing_client_app()

t()

Functions

allow_client_incoming(client_name)

Gives the device a client name allowing incoming connections to the client identified by the provided client_name.

allow_client_incoming(capability_struct, client_name)

allow_client_outgoing(app_sid)

Gives the device an application sid so that Twilio can determine the voice URL to use to handle any outgoing connection.

allow_client_outgoing(app_sid, app_params)

allow_client_outgoing(capability_struct, app_sid, app_params)

generate_and_sign(extra_claims \\ %{}, key \\ __default_signer__())

Combines generate_claims/1 and encode_and_sign/2

generate_and_sign!(extra_claims \\ %{}, key \\ __default_signer__())

Same as generate_and_sign/2 but raises if error

new()

Initialises a new capability specification with a TTL of one hour, and the account sid and auth token taken from the configuration.

starting_at(capability_struct, start_time)

Sets the time at which the TTL begins in seconds since epoch.

token(capability_struct)

Generates a JWT token based on the requested capabilities that can be provided to the Twilio client. Supports clients with multiple capabilties.

verify_and_validate(bearer_token, key \\ __default_signer__(), context \\ %{})

Combines verify/2 and validate/1

verify_and_validate!(bearer_token, key \\ __default_signer__(), context \\ %{})

Same as verify_and_validate/2 but raises if error

with_account_sid(capability_struct, account_sid)

Sets the Twilio account sid used to issue the token.

with_auth_token(capability_struct, auth_token)

Sets the Twilio account auth token used to sign the capability token.

with_ttl(capability_struct, ttl)

Sets the TTL of the token in seconds.

Link to this section Types

outgoing_client_app()

Specs

outgoing_client_app() :: {String.t(), map()}

t()

Specs

t() :: %ExTwilio.Capability{
  account_sid: String.t() | nil,
  auth_token: String.t() | nil,
  incoming_client_names: list(),
  outgoing_client_app: outgoing_client_app() | nil,
  start_time: non_neg_integer() | nil,
  ttl: non_neg_integer() | nil
}

Link to this section Functions

allow_client_incoming(client_name)

Specs

allow_client_incoming(String.t()) :: t()

Gives the device a client name allowing incoming connections to the client identified by the provided client_name.

Incoming capability docs

Example

A device with this token will be identified as tommy

ExTwilio.Capability.allow_client_incoming("tommy")

allow_client_incoming(capability_struct, client_name)

Specs

allow_client_incoming(t(), String.t()) :: t()

allow_client_outgoing(app_sid)

Specs

allow_client_outgoing(String.t()) :: t()

Gives the device an application sid so that Twilio can determine the voice URL to use to handle any outgoing connection.

Outgoing capability docs

Example

Outgoing connections will use the Twilio application with the SID: APabe7650f654fc34655fc81ae71caa3ff

ExTwilio.Capability.allow_client_outgoing("APabe7650f654fc34655fc81ae71caa3ff")

allow_client_outgoing(app_sid, app_params)

Specs

allow_client_outgoing(String.t(), map()) :: t()

allow_client_outgoing(t(), String.t()) :: t()

allow_client_outgoing(capability_struct, app_sid, app_params)

Specs

allow_client_outgoing(t(), String.t(), map()) :: t()

generate_and_sign(extra_claims \\ %{}, key \\ __default_signer__())

Specs

generate_and_sign(Joken.claims(), Joken.signer_arg()) ::
  {:ok, Joken.bearer_token(), Joken.claims()} | {:error, Joken.error_reason()}

Combines generate_claims/1 and encode_and_sign/2

generate_and_sign!(extra_claims \\ %{}, key \\ __default_signer__())

Specs

generate_and_sign!(Joken.claims(), Joken.signer_arg()) ::
  Joken.bearer_token() | no_return()

Same as generate_and_sign/2 but raises if error

new()

Specs

new() :: t()

Initialises a new capability specification with a TTL of one hour, and the account sid and auth token taken from the configuration.

Example

ExTwilio.Capability.new

starting_at(capability_struct, start_time)

Specs

starting_at(t(), non_neg_integer()) :: t()

Sets the time at which the TTL begins in seconds since epoch.

Example

Sets the TTL to begin on 24th May, 2016

ExTwilio.Capability.starting_at(1464096368)

token(capability_struct)

Specs

token(t()) :: String.t()

Generates a JWT token based on the requested capabilities that can be provided to the Twilio client. Supports clients with multiple capabilties.

Multiple capability docs

Example

Generates and signs a token with the provided capabilities

ExTwilio.Capability.token

verify_and_validate(bearer_token, key \\ __default_signer__(), context \\ %{})

Specs

verify_and_validate(Joken.bearer_token(), Joken.signer_arg(), term()) ::
  {:ok, Joken.claims()} | {:error, Joken.error_reason()}

Combines verify/2 and validate/1

verify_and_validate!(bearer_token, key \\ __default_signer__(), context \\ %{})

Specs

verify_and_validate!(Joken.bearer_token(), Joken.signer_arg(), term()) ::
  Joken.claims() | no_return()

Same as verify_and_validate/2 but raises if error

with_account_sid(capability_struct, account_sid)

Specs

with_account_sid(t(), String.t()) :: t()

Sets the Twilio account sid used to issue the token.

Example

Sets the account sid to be XXX

ExTwilio.Capability.with_account_sid('XXX')

with_auth_token(capability_struct, auth_token)

Specs

with_auth_token(t(), String.t()) :: t()

Sets the Twilio account auth token used to sign the capability token.

Example

Sets the auth token to be XXX

ExTwilio.Capability.with_auth_token('XXX')

with_ttl(capability_struct, ttl)

Specs

with_ttl(t(), non_neg_integer()) :: t()

Sets the TTL of the token in seconds.

TTL docs

Example

Sets the TTL to one hour

ExTwilio.Capability.with_ttl(3600)