From DocuSign, this is Developing with
DocuSign. I'm Larry Kluger a member of the
DocuSign dev center team. In this video
I'll be discussing integration keys: what
they are, when you need them, what they do
and much more. To build an application
that integrates with DocuSign via one of
our APIs you usually need an
integration key. There are some
exceptions. The DocuSign signature
appliance does not use integration keys
and there are some Connect webhook
applications that don't need integration
keys either. If you're planning to use an
application from an independent software
vendor, an ISV, ask the ISV if they'll be
supplying the IK or if you will need to.
I'll discuss more about ISV applications
later in the video. An integration key
represents an application so it has one
owner. The application with its IK can
be used by anyone on any account that
includes API support. Let's start with
the basic API call. Most DocuSign APIs
require that an OAuth access token is
included with every API request. The
access token is sent to DocuSign in the
authorization HTTP header of the API
request. To obtain an access token
your application needs an integration
key.
We recommend that your application uses
an OAuth flow and the DocuSign
authentication server to obtain access
tokens. By using OAuth your application
authenticates on behalf of your user
without seeing the user's password.
During the early stages of development
you can also hard code an access token,
but that can only be a temporary step
since access tokens only last a maximum
of eight hours. An integration key is an
alphanumeric identifier used to identify
your application. It uses the GUID or
global universal ID format. You can see
an example of an integration key on the
screen. The terms integrator key,
integration key, and client ID are all
synonyms and mean the same thing. The
OAuth community uses the term client ID.
DocuSign prefers the term integration
key but has used integrator key in the
past. Each of your applications should
have its own integration key. New
versions of an application do not need a
new IK. In this video I'll be using the
terms integration
key and client ID. Note that none
of the integration keys or other private
information shown in this video are real,
they're all examples that do not
actually work on the DocuSign systems.
Integration keys are unique within the
scope of the DocuSign sandbox system,
that is the demo system. A demo
integration key is different from a
production integration key even if they
have the same value. They have two
different management accounts and two
different sets of settings. For example
you use the developer sandbox system
to create integration key, 1-2-3.
When your application is ready for
production
you'll complete the go-live process. You
now have two different integration keys,
both have the value 1-2-3. They will
have different secrets and other
settings. The first one can still be used
on the demo system, the second one can be
used on the production systems. If you've
purchased an application from an
independent software vendor, an ISV, that
is integrated with DocuSign you may, or
may not, need your own integration key.
ISV applications should usually include
their own integration key. Ask your ISV
or the person installing your software
whether or not you'll need your own IK
for the application. If you will need
your own IK then the software vendor
should help you create the integration
key and move it to the production
systems. Integration key charges. Creating,
testing, and using integration keys is
free on the developer sandbox system.
Moving an integration key to the
production systems, that's the go-live
process, is also free. Envelope charges
are based on the user and their
production account plan, not on the
application used. For example, Daryl
Developer creates an application and
integration key. Charlie Customer uses
the application. Charlie is charged for
his DocuSign production account usage,
Daryl is not. Using an integration key.
An integration key can be used by any
user on any account that includes API
support to obtain an access token. You do
not have to enable access to an account.
All IKs can always be used by any
account. Managing an IK: exactly one
account, the IK's management account, is used
to manage an IK
to view and change its settings. An
integration key's management account is
simply a DocuSign account that can
change the IK settings. When you create
an IK demo, the account you used
becomes the management account for the
new IK. When you use the go-live process
to enable the IK on production you
choose which paid production account
will also become the production
management account for the IK. Software
vendors who are a member of the DocuSign
Partner Program can obtain a no charge
partner account on the production
systems that can be used to manage
production integration keys. All
integration keys are created in the
developer sandbox system, that's
demo.docusign.net. When your application is
ready for the production system, the
go-live process is used. After the go-live
process you will have two integration
keys:
the original integration key on demo and
a new integration key, same value but
different settings, on production.
You can still use your original IK on
demo after completing the go-live
process. Integration Keys have many
attributes and more may be added in the
future. You can view and update an
integration key's attributes by using
the administration tool on the key's
management account. An IK in production
can be used by any user in any account
that includes API access on any DocuSign
platform. North America, Europe, Australia,
etc. Users will only have access to your
application if you provide your
application to the user. Your application
can only use the API methods and
features included in the account's plan.
For example, payments are not included in
all types of accounts. You cannot delete
in IK. Instead, rename it to old and
deleted its secret(s), private key(s), etc.
These next couple of slides are for
independent software vendors. If your
software is a cloud-based application
then your application should have one
integration key which you control and
manage. Your customers do not, and should
not, need to create or manage an IK. Your
customers do not need to know your
application's IK and must not know
your IK's secret(s) or private key(s). You
should use authorization code grant
whenever a user is present to configure or
use your application. If your application
is installed on-premises then each of
your customers should have their own
production IK. The best option is for you
to generate the IK, then use the go-live
process and work with your customer to
move the IK to production. The management
account should belong to your customer.
In the future, if your application is
on-premises then our plan is that you,
the ISV, will be able to create IKs
for your customers. These IKs will be
available on production immediately with
no go-live process required. They will be
associated with your application's IK. If
you're interested in this plan, please ask
your DocuSign representative or
customer service to add your name and
account information to internal tracking
number "DPE-136." Thank you very much
for watching this video about DocuSign
integration keys and thank you for
integrating with DocuSign.